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 ¶
const Path = "/v1/ws"
Path is the WebSocket endpoint. The ingress exposes it and SlotPath publicly, the health probes only internally.
const SlotPath = "/v1/slot"
SlotPath is the HTTP endpoint that returns the slot of a token's owner. It needs Options.Tokens.
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 (*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.
type SlotInfo ¶ added in v0.3.0
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.