server

type Account struct {
	ID        string
	Unmetered bool
	Rev       uint64
}

type AdoptKey struct {
	Account string
	Hash    [32]byte // SHA-256 of the key
	Uses    int      // left
	Expires time.Time
}

type Backend interface {
	// ReadAddress reads what is held of address a, strongly consistent:
	// its mailbox's record and its identity's revocations, each nil if absent.
	ReadAddress(ctx context.Context, a protocol.Address) (*Mailbox, *Revocations, error)
	// ReadLive reads a mailbox's live messages, strongly consistent: what a
	// mailbox's load counts (Memory.readMailbox).
	ReadLive(ctx context.Context, mailbox protocol.Address) ([]Header, error)
	// List returns up to limit live headers, oldest first by (ReceivedAt,
	// ID), after the given key (nil: from the start); strongly consistent
	// where consistent is set.
	List(ctx context.Context, mailbox protocol.Address, after *Cursor, limit int, consistent bool) ([]Header, error)
	// Message returns a live message and its body, from byte from on where
	// from is inside it, above 0 and below its Size, and otherwise whole; or
	// ErrNotFound; or errNoBody for a live item whose body is gone.
	Message(ctx context.Context, mailbox protocol.Address, id [32]byte, from int64) (*Header, []byte, error)
	// Dedupe returns the header of the live message mailbox holds with this
	// id, or ErrNotFound.
	Dedupe(ctx context.Context, mailbox protocol.Address, id [32]byte) (*Header, error)
	// Account reads an account's record, strongly consistent, or returns
	// ErrNotFound.
	Account(ctx context.Context, id string) (*Account, error)
	// AdoptKey reads an adopt key's state, strongly consistent, or returns
	// ErrNotFound.
	AdoptKey(ctx context.Context, account string, hash [32]byte) (*AdoptKey, error)

	// CreateMailbox stores b's record, at b.Rev, if the address has none;
	// otherwise ErrExists.
	CreateMailbox(ctx context.Context, b *Mailbox) error
	// UpdateMailbox stores b's record at b.Rev+1 if the stored one is at b.Rev;
	// otherwise ErrStale. It writes nothing of the revocations, and leaves b
	// as it is.
	UpdateMailbox(ctx context.Context, b *Mailbox) error
	// DeleteMailbox deletes a's record, and keeps its revocations.
	DeleteMailbox(ctx context.Context, a protocol.Address) error
	// Revoke keeps what the identity of address a revoked (Store.Revoke),
	// and returns the address's revocations as they now are; ErrStale if a
	// revocation of certificates through as high a serial was stored first,
	// or if the address's revocations item is not what want asks: there, or
	// not. The item exists only holding a revocation, since none is written
	// that holds neither, so that is whether any is held.
	Revoke(ctx context.Context, a protocol.Address, rv *Revocations, want Expect) (*Revocations, error)
	// Adopt moves mailbox b, at b.Rev, into account, spending a use of the
	// account's adopt key whose hash is key, in one write: ErrStale,
	// ErrKeyRefused.
	Adopt(ctx context.Context, b *Mailbox, account string, key [32]byte) error
	// Leave takes mailbox b, at b.Rev, out of its account, or returns ErrStale.
	Leave(ctx context.Context, b *Mailbox) error
	// CreateAccount stores a new account at a.Rev, or returns ErrExists.
	CreateAccount(ctx context.Context, a *Account) error
	// PutAdoptKey stores a new adopt key's state, or returns ErrExists.
	PutAdoptKey(ctx context.Context, k *AdoptKey) error
	// PutMessage stores a message: its body, then its item. A live item of
	// another send of the id refuses it (duplicate).
	PutMessage(ctx context.Context, mailbox protocol.Address, h *Header, body []byte) error
	// Retire deletes a live message's item, so it leaves the list and
	// nothing of it is kept, and returns when it was received; ErrNotFound
	// if it is not live.
	Retire(ctx context.Context, mailbox protocol.Address, id [32]byte) (time.Time, error)
	// DeleteMessage acks a message: its body goes, then it is retired.
	DeleteMessage(ctx context.Context, mailbox protocol.Address, id [32]byte) (time.Time, error)
	// DeleteAll deletes, as acks do, every live message in a mailbox, and hands
	// each retired as its item is deleted. A message already gone is no
	// error.
	DeleteAll(ctx context.Context, mailbox protocol.Address, retired func(id [32]byte, received time.Time)) error

	// Start hands every change to what the backend keeps, from then on, to
	// apply: in order for each item, and at least once. It returns once the
	// feed is followed, and the feed ends with ctx.
	Start(ctx context.Context, apply func(Change)) error
	// Ready reports whether the feed is followed.
	Ready() bool
}

type Change struct {
	Kind ChangeKind
	// Addr is the record's address, the revocations', or the message's mailbox.
	Addr protocol.Address
	// AccountID is the account's id.
	AccountID string
	// Gone is an item deleted.
	Gone bool
	// Err is an item whose image does not read.
	Err error

	Mailbox     *Mailbox     // RecordChange
	Revocations *Revocations // RevocationsChange
	Header      *Header      // MessageChange: of an item deleted, its ID alone
	Live        bool         // MessageChange: in the list
	Account     *Account     // AccountChange
}

type ChangeKind int

type Config struct {
	Store  Store
	Limits Limits
	Now    func() time.Time // time.Now if nil
	Log    *log.Logger      // no access log if nil
	// Ready, when set, reports whether the store has loaded its memory; until
	// it has, every call is answered 503 rather than wrong (ARCHITECTURE.md
	// § Startup).
	Ready func() bool
	// TrustedProxies are the peers whose X-Forwarded-For names the client
	// (clientIP): behind a reverse proxy every request arrives from the
	// proxy's address. From any other peer the header is ignored. None:
	// the peer is always the client.
	TrustedProxies []netip.Prefix
	// Names are the names clients call this server by: the host of its URL,
	// lowercase, with its port only when that is not the scheme's default. A
	// pass is taken only on a request whose Host, written so, is one of them
	// (PROTOCOL.md §8). None: any Host
	// is taken, which is for the dev server and tests only, since a pass
	// made for another server would then pass here.
	Names []string
	// IdentityTypes are the identity key types this server registers: some
	// of protocol.IdentityTypes, ssh-ed25519 among them, since that is the
	// one every client makes and verifies (PROTOCOL.md §4.1). None: every type
	// this build verifies.
	IdentityTypes []string
	// SiteBackend, when set, is the web server every request outside /v1/
	// and /to/, the API's and the link page's, is passed to (SiteBackend,
	// siteProxy). None: those paths are 404.
	SiteBackend *url.URL
	// Metrics, when set, count what the server does and refuses
	// (NewMetrics). None: nothing is counted.
	Metrics *Metrics
}

type Cursor struct {
	ReceivedAt time.Time
	ID         [32]byte
}

type DynamoConfig struct {
	AWS                                                  aws.Config
	MailboxesTable, MessagesTable, AccountsTable, Bucket string
	Now                                                  func() time.Time // time.Now if nil
	// MailboxCache is how many mailbox records memory holds, as many account
	// records, and as many mailboxes remembered as missing; 0: none.
	MailboxCache   int
	StreamInterval time.Duration // how often each stream shard is read
	Log            *log.Logger   // nil: no log
	// ConsistentReads makes every read strongly consistent, at twice the
	// read units: for tests, which read back what they wrote within
	// milliseconds. Otherwise only the reads that fill memory are, a mailbox's
	// load and a read of what is held of an address, since a stale copy
	// there would decide later answers, and the page of a list asked to
	// wait, which a client may hold on: a strongly consistent read costs
	// twice the read units, and polls are the load, which never fill. A
	// stale read elsewhere costs a retry or one poll; the conditional writes
	// keep the data right.
	ConsistentReads bool
	// Fatal is called if a stream follower loses its place in its stream.
	// Memory can no longer be shown current; the process must restart, which
	// rebuilds it from the tables.
	Fatal func(error)
	// Metrics, if set, count the caches' hits, misses and evictions, how far
	// behind each stream memory follows, and how large each mailbox's item
	// collection a message write grows is. Calls to AWS are counted by
	// Metrics.InstrumentAWS on the AWS config.
	Metrics *Metrics
}

type Expect int

type Header struct {
	ID         [32]byte // SHA-256 of the ciphertext
	Size       int
	ReceivedAt time.Time // to the millisecond
	ExpiresAt  time.Time
}

type Indebted struct {
	Key    string `json:"key"`
	FullIn int64  `json:"full_in"` // seconds, rounded up
}

type Limits struct {
	MaxSize        int           // the cap on a ciphertext, in bytes, and what a send reads of its body; nothing may depend on its value
	MailboxCap     int           // total per mailbox, a storage ceiling [tunable]
	SendsPerDay    int           // per sender, a number a day: that many at once, one back each day divided by it (decided: 20)
	PollBurst      int           // polls a mailbox may make at once (decided: 10); also the fetches of messages already fetched
	PollRefill     time.Duration // one more poll each (decided: 50 s; once a minute is stated); also one more such fetch
	PollAfter      int           // seconds, told to clients (decided: 60)
	MaxWait        time.Duration // the longest a list is held, whatever its wait asks (PROTOCOL.md §11.11) [tunable]
	MaxHeldLists   int           // lists this process holds at once; past it a held list is answered 503 (0: none held) [tunable]
	AccountMaxSize int           // the most an account lifts MaxSize to, so what a send reads first; up to MaxSize, nothing
	RenewalsPerDay int           // prekey renewals per mailbox, a number a day as SendsPerDay (decided: 10), so no mailbox can spend the mailboxes table's write capacity
	RetiredKept    int           // retired prekeys a mailbox record keeps for the new-key rule, newest first (decided: 10), so a record stays small

	RegistrationsPerHour      int // per IPv4 address or IPv6 /64 [tunable]
	RangeRegistrationsPerHour int // per IPv6 /48, beside the /64's (decided: 500, Let's Encrypt's ratio of the two, until measured)
	SendsPerMinutePerIP       int // the pre-auth send rate per IP [tunable]
	MissesPerMinute           int // per IP: reads of the mailboxes table that find no mailbox, and checks that fail (decided: 10 for now)

	// Requests is the flood budget of an IPv4 address or IPv6 /64: every call
	// with no pass and every request no route matches (decided: 100 at once,
	// 50 a second).
	RequestBurst  int
	RequestRefill time.Duration

	// Budgets: a burst at once and one more each refill (LIMITS.md).
	ReceiveBurst                 int           // per mailbox: new messages it takes, from all senders together (decided: 50, on, and never off: ReceiveCeiling)
	ReceiveRefill                time.Duration // (decided: 6 s, ten a minute; never shorter than ReceiveCeiling, which an account lifts it to)
	DrainBurst                   int           // per mailbox: its first fetches of held messages, spent only by its own calls (decided: 50, on); an account lifts it
	DrainRefill                  time.Duration // (decided: 6 s, ten a minute)
	CallBurst                    int           // per mailbox: its calls with its pass that no other budget counts [tunable]; an account lifts it
	CallRefill                   time.Duration // [tunable]
	CertificatesPerDay           int           // per mailbox, a number a day: renewals under a later certificate, but for one that replaces a revoked certificate (decided: 10, as renewals)
	CertificateRevocationsPerDay int           // per mailbox, a number a day: raises of its revocation of certificates (decided: a count of its own, apart from CertificatesPerDay; 10, as that one) [tunable]

	// ACLEntries is the most entries a mailbox's ACL holds, its two lists
	// together [tunable]: a mailbox's record, with its ACL, is held in the mailbox
	// cache, so this bounds what one record costs memory there. Never off,
	// and at most protocol.MaxACLEntries: dromas-server serve does not start
	// otherwise.
	ACLEntries int

	// How long a body may take: BodyTimeout, and one second more for each
	// BodyMinRate bytes its handler reads, as Apache's RequestReadTimeout
	// counts; each write of a response the same, for the bytes of it already
	// written. A body that stops coming is cut off after BodyTimeout. What the
	// server drains of a body after its handler has what the handler's reads
	// left, and the answer's time runs from the end of the drain (paced). It
	// is also the longest a send waits for the one large read.
	BodyTimeout time.Duration // [tunable]
	BodyMinRate int           // bytes a second [tunable]

	// HeadBytes is the most of a request's head, its request line and its
	// headers, that the server reads (http.Server.MaxHeaderBytes): what the
	// longest call needs, a pass of protocol.MaxPassAuthorization bytes
	// with the request line and the other headers a client and a proxy in
	// front of it send, and no more (decided: 8 KiB, least need).
	// A head is read before any count, since the address a call is counted
	// by may be one of its headers (LIMITS.md, rule 1).
	HeadBytes int
	// HeadTimeout is how long a request's head may take to arrive
	// (http.Server.ReadHeaderTimeout), before any handler sees it.
	HeadTimeout time.Duration
}

type Mailbox struct {
	Addr     protocol.Address
	Identity []byte // the identity document, exactly as registered or as the revocations carried it
	State    State
	// The current prekey: its statement, the working key's signature over it,
	// which carries the key's certificate, and the statement parsed.
	Statement []byte
	Signature []byte
	Prekey    *protocol.Prekey
	// The certificate Signature carries, which is the mailbox's current one: its
	// serial, and the SHA-256 of its bytes. A pass is taken only under it,
	// and a prekey only under it or a later one (PROTOCOL.md §5). A mailbox's
	// statements are ordered by this serial first, and by the prekey's own
	// second.
	CertSerial uint64
	Cert       [32]byte
	// SenderKeyTypes is what the mailbox declared with its current prekey: the
	// identity key types of the senders it takes messages from, or
	// protocol.AnySender (PROTOCOL.md §7). Only names this build verifies
	// are kept (declared): a mailbox of any other type cannot send here.
	SenderKeyTypes []string
	// Retired holds the newest retired prekeys (Limits.RetiredKept), each
	// until its not_after: its key may not come back.
	Retired []Retired
	Rev     uint64 // the record's revision, 0 with no record; a write must name the one it read
	Created time.Time
	// Expires is when the record may go: DynamoDB's TTL deletes it some time
	// after (PROTOCOL.md §13). Every registration and renewal moves it to
	// when nothing of the mailbox is valid any more. Zero: never.
	Expires time.Time
	// Account is the account the mailbox belongs to, or "" (PROTOCOL.md §11.16).
	// Only Adopt and Leave change it.
	Account string
	// What the identity revoked, from the address's revocations item
	// (Revocations): kept for good and served to whoever asks.
	//
	// Revocation is the identity's signature that revoked the address
	// (PROTOCOL.md §10.1): nil unless State is Revoked. With Identity it
	// proves itself, so nobody takes this server's word that the mailbox is
	// revoked.
	Revocation []byte
	// RevokedCerts is the identity's highest revocation of its certificates,
	// exactly as it signed it, and RevokedCertsSig its signature
	// (PROTOCOL.md §10.2): nil until one is published. The address goes on.
	// Served with Identity to whoever asks, it proves itself as Revocation
	// does. It was verified when it was stored, and only one through a higher
	// serial replaces it.
	RevokedCerts    []byte
	RevokedCertsSig []byte
	// ACL is the mailbox's sender ACL (PROTOCOL.md §11.14): who may send to it,
	// deny read first and then allow. nil until the mailbox puts one, and a mailbox
	// with none takes messages from everyone. It is replaced whole, and never
	// removed.
	ACL *protocol.ACL
}

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

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

type Retired struct {
	Type     protocol.KeyType
	NotAfter time.Time
	KeyHash  [32]byte // SHA-256 of the age recipient
}

type Revocations struct {
	Identity []byte
	// Address is the identity's signature that revoked the address, or nil.
	Address []byte
	// Certs and CertsSig are its highest revocation of its certificates, or
	// nil; Through is the serial it revokes through, 0 with none.
	Certs, CertsSig []byte
	Through         uint64
}

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

type Standing struct {
	State State
	Key   string   // the identity's key in SSH wire form, of whatever type: what line 2 of its document holds
	Cert  [32]byte // Mailbox.Cert
	// CertSerial is Mailbox.CertSerial, which Listed is judged by.
	CertSerial uint64
	// Listed is true while the mailbox's current certificate is one its identity
	// has revoked (PROTOCOL.md §10.2): no pass of the mailbox is taken until it
	// publishes a prekey under a new certificate.
	Listed bool
	// InAccount is true for a mailbox in an account, whose limits are read from
	// it; a mailbox in none has the server's, with nothing to read.
	InAccount bool
}

type State string

type Store interface {
	// Held returns the standing of a mailbox memory holds, with no read. ok is
	// false for a mailbox this process has not loaded, which only its record
	// answers for: Known, then Mailbox (ARCHITECTURE.md § Memory).
	Held(a protocol.Address) (st Standing, ok bool)
	// Changed returns a channel closed at mailbox a's next change in memory, by
	// a write of this process or one the streams bring: what a held list
	// waits on (PROTOCOL.md §11.11). It reads nothing.
	Changed(a protocol.Address) <-chan struct{}
	// NextExpiry returns when the first of mailbox a's messages in memory
	// expires, by the store's clock, with no read: past, for one that
	// expired since the mailbox was last read; zero for a mailbox with none, or one
	// memory has not loaded. An expiry is no change memory applies, so a
	// held list waits until it, and no longer (PROTOCOL.md §11.11).
	NextExpiry(a protocol.Address) time.Time
	// Mailbox returns what is held of an address (view): its mailbox's record and
	// its identity's revocations, or ErrNotFound if neither.
	Mailbox(ctx context.Context, a protocol.Address) (*Mailbox, error)
	// Known returns what memory holds of an address, with no read: what Mailbox
	// returns, or nil for an address it holds as missing. ok is false when
	// only a read can tell, which is what Mailbox then does.
	Known(a protocol.Address) (b *Mailbox, ok bool)
	// Begin returns a token of address a, which only grows: what Mailbox
	// answers once it is taken holds every write this process applied to a
	// before it.
	Begin(a protocol.Address) uint64
	// CreateMailbox stores a new mailbox's record at Rev 1, or returns ErrExists if
	// the address has one.
	CreateMailbox(ctx context.Context, b *Mailbox) error
	// UpdateMailbox stores b's record if the stored one is still at b.Rev, and
	// bumps b.Rev; otherwise ErrStale. It writes nothing of the revocations.
	UpdateMailbox(ctx context.Context, b *Mailbox) error
	// DeleteMailbox deletes a's record, and keeps its revocations.
	DeleteMailbox(ctx context.Context, a protocol.Address) error
	// Revoke keeps what the identity of address a revoked, mailbox or none, in
	// the address's revocations item: rv's revocation of the address, kept
	// once, and its revocation of certificates, which only one through a
	// higher serial replaces: ErrStale if one through as high a serial was
	// stored first, or if the address's revocations are not what want asks
	// of them, some held or none.
	Revoke(ctx context.Context, a protocol.Address, rv *Revocations, want Expect) error

	// Dedupe returns the header of the live message mailbox holds with this
	// id, or ErrNotFound: nothing is kept of one acked or expired.
	Dedupe(ctx context.Context, mailbox protocol.Address, id [32]byte) (*Header, error)
	// PutMessage stores a message: its body, then its header. If a live
	// message of the id appeared first, it returns that one's header
	// instead.
	PutMessage(ctx context.Context, mailbox protocol.Address, h *Header, body []byte) (*Header, error)
	// List returns up to limit live headers, oldest first by (ReceivedAt,
	// ID), after the given key (nil: from the start). Consistent reads them
	// strongly consistent: every write applied to memory before the read is
	// in the page.
	List(ctx context.Context, mailbox protocol.Address, after *Cursor, limit int, consistent bool) ([]Header, error)
	// Message returns a live message and its body, or ErrNotFound: the body
	// from byte from on where from is inside it, above 0 and below its Size,
	// and otherwise whole, as a fetch answers a range (PROTOCOL.md §11.12).
	// So a fetch that resumes reads only the rest from where a body is kept.
	Message(ctx context.Context, mailbox protocol.Address, id [32]byte, from int64) (*Header, []byte, error)
	// DeleteMessage acks a message: its body goes, then its item, and
	// nothing of it is kept (PROTOCOL.md §13). ErrNotFound if it is not
	// live.
	DeleteMessage(ctx context.Context, mailbox protocol.Address, id [32]byte) error
	// DeleteMessages deletes every live message in a mailbox, as acks do (a
	// revocation of its address). A message already gone is no error.
	DeleteMessages(ctx context.Context, mailbox protocol.Address) error

	// Account returns an account's record, or ErrNotFound: read on its
	// first use, then answered from memory.
	Account(ctx context.Context, id string) (*Account, error)
	// CreateAccount stores a new account at Rev 1, or returns ErrExists.
	CreateAccount(ctx context.Context, a *Account) error
	// PutAdoptKey stores a new adopt key's state, or returns ErrExists.
	PutAdoptKey(ctx context.Context, k *AdoptKey) error
	// AdoptKey returns the state of account's adopt key whose hash is given,
	// or ErrNotFound. It reads it strongly consistent, so a key just made is
	// found.
	AdoptKey(ctx context.Context, account string, hash [32]byte) (*AdoptKey, error)
	// Adopt moves mailbox b, as read, into account, spending a use of account's
	// adopt key whose hash is given, in one write: ErrStale if the record
	// changed, ErrKeyRefused if the key is spent, expired or gone. It sets
	// b.Account and bumps b.Rev.
	Adopt(ctx context.Context, b *Mailbox, account string, key [32]byte) error
	// Leave takes mailbox b, as read, out of its account, or returns ErrStale.
	// It clears b.Account and bumps b.Rev.
	Leave(ctx context.Context, b *Mailbox) error

	// Count returns the number of live messages in a mailbox, from memory: the
	// mailbox is loaded on its first use, and answered from memory after that.
	Count(ctx context.Context, mailbox protocol.Address) (n int, err error)
	// After returns how many live messages a mailbox holds past a list position,
	// from memory as Count does: what a list from that cursor would return.
	After(ctx context.Context, mailbox protocol.Address, c *Cursor) (int, error)
	// Holds reports whether a mailbox holds a live message with this id, from
	// memory as Count does. False is certain; true may be another message
	// whose id starts alike, so the caller still reads it.
	Holds(ctx context.Context, mailbox protocol.Address, id [32]byte) (bool, error)
	// Fetched is Holds for a fetch: it also reports whether this process has
	// served the message before, and counts this serving. The count lives
	// with the message in memory, so a restart forgets it.
	Fetched(ctx context.Context, mailbox protocol.Address, id [32]byte) (held, again bool, err error)
}