@wellknown-id/mailbox

#Interfaces

#MailboxStorage

What a mailbox keeps, as text by kind and id. Synchronous, so a request reads and writes without interleaving.

#Methods

#delete()

delete(kind, id): void;

#Parameters

#Returns

void

#get()

get(kind, id): string | undefined;

#Parameters

#Returns

string | undefined

#ids()

ids(kind): Iterable<string>;

Every id held of a kind (for counting what's held at start, and for garbage collection).

#Parameters

#Returns

Iterable<string>

#put()

put(
   kind, 
   id, 
   text
): void;

#Parameters

#Returns

void

#size()

size(kind, id): number;

The bytes held under an id, 0 for none.

#Parameters

#Returns

number

#Type Aliases

#GcOptions

type GcOptions = object;

When garbage collection runs: every intervalMs (0: never by the clock), and after every everyRequests requests (0: never).

#Properties

#Kind

type Kind = "store" | "box" | "drop";

What a mailbox keeps: blobs (store), records boxes (box) and drop boxes (drop).

#MailboxHandler

type MailboxHandler = (req, res) => void & object;

A Node HTTP request handler answering the mailbox's API, with garbage collection on demand and a way to stop.

#Type Declaration

#MailboxOptions

type MailboxOptions = object;

How a mailbox is made: where it keeps things, who may use it from a web page, and its limits.

#Properties

#ServerOptions

type ServerOptions = Partial<Omit<MailboxOptions, "storage">> & object;

A mailbox server's options: the mailbox's own (MailboxOptions, but storage), and a directory to keep files in.

#Type Declaration

#StoreLimits

type StoreLimits = typeof STORE_LIMITS;

A mailbox's limits (STORE_LIMITS has the defaults and what each is for).

#Variables

#GC_DEFAULTS

const GC_DEFAULTS: GcOptions;

Garbage collection by default: hourly, and after every 1000 requests, 200 ids at a time.

#KINDS

const KINDS: readonly Kind[];

Every kind, in the order storage lists them.

#STORE_LIMITS

const STORE_LIMITS: object;

The default limits: sizes per blob, records entry and drop-box item, what's held in all, and writes per client.

#Type Declaration

#Functions

#clientOf()

function clientOf(req): string;

Which client a request is from, for its bucket only: the address the nearest proxy saw (the rightmost X-Forwarded-For).

#Parameters

#Returns

string

#createMailboxServer()

function createMailboxServer(opts?): Server<typeof IncomingMessage, typeof ServerResponse> & object;

A server answering the mailbox's API (and GET {prefix}/health), not yet listening.

#Parameters

#Returns

Server<typeof IncomingMessage, typeof ServerResponse> & object

#fileStorage()

function fileStorage(dir): MailboxStorage;

Storage in files under dir: {dir}/{kind}/{id}.json, each written whole (to a temporary file, then renamed).

#Parameters

#Returns

MailboxStorage

#mailboxHandler()

function mailboxHandler(opts): MailboxHandler;

The mailbox's HTTP handler.

#Parameters

#Returns

MailboxHandler

#memoryStorage()

function memoryStorage(): MailboxStorage;

Storage in memory: gone when the process ends.

#Returns

MailboxStorage

#writeBuckets()

function writeBuckets(limits, now?): object;

Token buckets by client, in memory only; full buckets are forgotten.

#Parameters

#Returns