protocol

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package protocol implements the server side of the sqlite-remote protocol over WebSocket. The message types in internal/gen are generated from proto/sqlite_remote/v1/sqlite_remote.proto. proto/ is a copy of the definition in sqlite-remote-vfs and is updated with scripts/sync-proto.sh.

Index

Constants

View Source
const Path = "/v1/ws"

Path is the WebSocket endpoint. The ingress exposes it and SlotPath publicly, the health probes only internally.

View Source
const SlotPath = "/v1/slot"

SlotPath is the HTTP endpoint that returns the slot of a token's owner. It needs Options.Tokens.

View Source
const Version = 1

Version is the protocol version of this server.

Variables

This section is empty.

Functions

This section is empty.

Types

type Options

type Options struct {
	Store store.Store
	Log   *slog.Logger
	// MaxFrameBytes limits the size of every frame in both directions.
	MaxFrameBytes uint32
	// PingInterval is the ping interval sent to clients. A connection without a frame for three intervals is
	// closed.
	PingInterval time.Duration
	LeaseTTL     time.Duration
	// MaxCommitBytes limits the total block data of one commit across all its parts.
	MaxCommitBytes uint64
	// HelloTimeout is the time a new connection has to send its Hello.
	HelloTimeout time.Duration
	// AllowedOrigins lists the hosts from which a browser page may connect. In each pattern, `*` matches any part
	// of a host, e.g. `*.example.com` or `127.0.0.1:*`. Empty means same origin only. Clients other than browsers
	// send no Origin header and are not affected.
	AllowedOrigins []string
	// ServerID is the public address of this server, e.g. "wss://vfs.example/v1/ws". It is part of the transcript a
	// client signs at login. If it is empty, every login is rejected.
	ServerID string
	// ChallengeTTL is how long a challenge is valid. Zero means 30 s.
	ChallengeTTL time.Duration
	// Tokens, if set, admits only clients with a valid access token bound to their key. After the token has expired,
	// plus the verifier's leeway, the connection is closed at the next frame other than a Ping. Pings keep the
	// leases renewed until the client reconnects with a new token.
	Tokens *token.Verifier
	// Now returns the current time. Nil means time.Now.
	Now func() time.Time
}

Options configures a Server.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server serves the protocol on WebSocket connections. A client logs in by signing a challenge with its private key. The server derives the client's subject from the public key.

func NewServer

func NewServer(opts Options) *Server

NewServer returns a Server for opts.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP upgrades the request to a WebSocket and serves it until the connection ends.

func (*Server) ServeSlot added in v0.3.0

func (s *Server) ServeSlot(w http.ResponseWriter, r *http.Request)

ServeSlot serves GET and OPTIONS on SlotPath. GET needs an access token in the Authorization header as "Bearer <token>". The token need not be bound to a key: the response says which slot the owner has, not what is in it. A client calls it before it has its key, to learn whether the owner already has a slot and with which label.

Browsers may call it from the same origin and from the hosts in Options.AllowedOrigins. Other origins get 403.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown closes every connection with StatusGoingAway and waits until all connections have ended or ctx is done. Clients reconnect, possibly to another server instance, and resume their leases there.

type SlotInfo added in v0.3.0

type SlotInfo struct {
	Label       string `json:"label"`
	ClaimedAtMs int64  `json:"claimedAtMs"`
}

SlotInfo describes a slot. The response does not name the key that holds it.

type SlotResponse added in v0.3.0

type SlotResponse struct {
	Slot *SlotInfo `json:"slot"`
}

SlotResponse is the JSON body of GET SlotPath. Slot is null if the owner has no slot.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL