Documentation
¶
Overview ¶
Package provider is a WebSocket CRDT transport reference implementation.
It authenticates the HTTP upgrade, compares an exact replica.Manifest before accepting binary changes, bounds messages and queued writes, and uses a replica.Inbox to tolerate duplicate and out-of-order delivery. It deliberately does not add TLS, durable storage, replay/outbox handling, membership, or a tombstone-GC policy. Applications must provide those boundaries themselves.
Index ¶
Constants ¶
const ( // Subprotocol identifies the reference provider's control and binary-change // envelope. It is not a CRDT frame format version. Subprotocol = "crdt-sync-v1" // BatchSubprotocol adds a bounded batch envelope while retaining a complete // Dot and canonical CRDT delta for every contained change. It is opt-in so // v1 peers retain their original wire contract. BatchSubprotocol = "crdt-sync-v2" )
Variables ¶
var ( // ErrInvalidConfig reports a missing or unsafe provider configuration. ErrInvalidConfig = errors.New("websocket provider: invalid configuration") ErrUnauthorized = errors.New("websocket provider: unauthorized") // ErrClosed reports use of a closed client. ErrClosed = errors.New("websocket provider: client is closed") // ErrBatchUnsupported reports a batch operation on a v1 connection. ErrBatchUnsupported = errors.New("websocket provider: batch subprotocol is not enabled") // ErrBatchLimit reports a batch that exceeds the configured item or message // limit before it reaches the network. ErrBatchLimit = errors.New("websocket provider: batch limit exceeded") )
Functions ¶
This section is empty.
Types ¶
type Authenticate ¶
Authenticate authenticates one HTTP upgrade request before it becomes a WebSocket connection. Returning an error rejects the request with HTTP 401.
type Authorize ¶
Authorize binds a proposed CRDT change to an authenticated peer and its negotiated manifest. At minimum it should prevent one peer from publishing under another logical replica actor.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client maintains one reference-provider WebSocket connection. It does not persist an outbox or automatically reconnect; callers decide retry and recovery policy.
func Dial ¶
func Dial(ctx context.Context, endpoint string, manifest replica.Manifest, config ClientConfig) (*Client, error)
Dial authenticates the WebSocket handshake through config.Header, verifies that the server returns the exact manifest, then starts receiving binary changes. The endpoint should use wss in production after the application has configured TLS.
func (*Client) Close ¶
Close terminates the connection without attempting to make a client-side durability claim. Callers should persist their own checkpoint first when a graceful recovery boundary is required.
func (*Client) Done ¶
func (client *Client) Done() <-chan struct{}
Done closes when the receive loop stops.
func (*Client) Publish ¶
Publish validates change against the connection manifest, then transmits its canonical delta envelope. A caller may safely retry a change after an ambiguous network result; receiver inboxes and the concrete CRDT must remain idempotent.
func (*Client) PublishBatch ¶ added in v1.0.21
PublishBatch validates and sends a bounded group of independently identified changes in one WebSocket message. The server admits each Dot individually, so retry and outbox logic must retain every original change.
type ClientConfig ¶
type ClientConfig struct {
Header http.Header
Policy crdt.ProtocolPolicy
MaxMessageBytes int
MaxActorBytes int
// EnableBatches negotiates BatchSubprotocol and allows PublishBatch. Each
// contained change retains its own Dot; v1 remains the default.
EnableBatches bool
MaxBatchChanges int
HandshakeTimeout time.Duration
WriteTimeout time.Duration
OnChange func(replica.Change) error
}
ClientConfig configures one reference-provider client. OnChange must pass each change to an application-owned, manifest-compatible replica.Inbox (or another equally durable delivery boundary).
type Config ¶
type Config struct {
Groups []*Group
Authenticate Authenticate
Authorize Authorize
OriginPatterns []string
MaxMessageBytes int
MaxActorBytes int
MaxQueuedMessages int
MaxBatchChanges int
HandshakeTimeout time.Duration
WriteTimeout time.Duration
}
Config configures a Handler. Authentication and authorization are required; callers must not rely on the CRDT frame checksum as an identity check.
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
Group owns a manifest-bound, bounded replica inbox and the live peers for that group. It has no operation log or snapshot store.
func NewGroup ¶
func NewGroup(config GroupConfig) (*Group, error)
NewGroup creates one manifest-bound in-memory receiver. Apply must use the concrete CRDT decoder with limits appropriate to the application, then apply the decoded delta without a partial update on error.
type GroupConfig ¶
type GroupConfig struct {
Manifest replica.Manifest
Frontier replica.Frontier
Policy crdt.ProtocolPolicy
MaxPendingChanges int
MaxPendingBytes int
Apply replica.ApplyDelta
}
GroupConfig describes one in-memory replication group at the reference provider. Frontier must come from the same durable transaction as the application CRDT state when a production application restores a group.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler implements an authenticated WebSocket endpoint for a fixed set of manifest-bound Groups.
func NewHandler ¶
NewHandler validates a reference provider configuration. The returned handler rejects cross-origin requests unless OriginPatterns explicitly authorizes their origin host.
Source Files