@formancy/server 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,7 +1,54 @@
-import { Scanner, ServerOptionsSources, Storage } from "@formancy/server-core";
-import { FastifyInstance } from "fastify";
+import { Completer, Scanner, ServerOptionsSources, Storage } from "@formancy/server-core";
+import { FastifyBaseLogger, FastifyInstance } from "fastify";
+import { FastifyRateLimitStoreCtor } from "@fastify/rate-limit";
 import postgres from "postgres";
 import { Readable } from "node:stream";
+//#region src/model-settings.d.ts
+/**
+ * Which model the environment names for the builders: none, or a provider, its key and
+ * the model.
+ *
+ * A function of the environment rather than lines in `main.ts`, as `fileStoreSettings` is:
+ * the rules are where a deployment goes wrong, and `main.ts` is a composition root no test
+ * imports. Constructing the adapter stays in `main.ts`; this only says which
+ * ([0165](../../../docs/decisions/0165-a-deployments-model-is-asked-through-its-server.md)).
+ */
+export declare const MODEL_PROVIDERS: readonly ["anthropic", "openai", "xai"];
+/** Anthropic's Claude, OpenAI's models, or xAI's Grok — each through its own key. */
+type ModelProvider = (typeof MODEL_PROVIDERS)[number];
+type ModelSettings = {
+  readonly kind: 'none';
+} | {
+  readonly kind: 'configured';
+  readonly provider: ModelProvider;
+  readonly apiKey: string;
+  readonly model: string;
+};
+type Environment = Readonly<Record<string, string | undefined>>;
+/**
+ * Absent — all three unset or blank — is a supported state, and the default: this
+ * deployment has no model, the server says so to the admin, and no prompt pane is drawn.
+ *
+ * Throws on anything in between, so the server refuses to start rather than starting
+ * without the model the operator thinks they configured: a key or a model with no
+ * provider, a provider formancy has no adapter for, or a provider without its key or
+ * its model. Throws too when the environment would add headers to every request the
+ * provider's SDK sends. **No provider has a default model.** A model id goes stale when
+ * the provider retires it, and then every turn fails as a model that could not be
+ * reached, after an upgrade nobody made; and which model runs is what the operator pays
+ * for. Neither is this file's to decide. The message never repeats a value, because the
+ * key is one.
+ */
+export declare function modelSettings(env: Environment): ModelSettings;
+//#endregion
+//#region src/routes/model.d.ts
+/** The deployment's model: which provider, which model, and the adapter that asks it. */
+interface DeploymentModel {
+  readonly provider: ModelProvider;
+  readonly model: string;
+  readonly completer: Completer;
+}
+//#endregion
 //#region src/file-store.d.ts
 /**
  * Where uploaded bytes live.
@@ -46,6 +93,40 @@ export declare function createLocalFileStore(root: string): FileStore;
  */
 export declare function sha256(bytes: Buffer): string;
 //#endregion
+//#region src/server-log.d.ts
+/**
+ * The server's log: a JSON line for every request, one for every error that answered one, and
+ * one for each thing a route or a background worker has to say
+ * ([0168](../../../docs/decisions/0168-the-log-is-built-from-a-list-of-fields.md)).
+ *
+ * **What keeps everything else out is construction, not a filter over text.** A line is made
+ * from the fields `LOG_FIELDS` names, each kept only when its value is of that field's kind,
+ * and from nothing else. A key a call hands over that is not on the list is never read, so a
+ * body, a header, a query string, an answer, a password, a draft's key or a file's name has no
+ * field to go in. The words of a call are never written at all — pino's message argument,
+ * Fastify's `error.message`, its `Route GET:/the/raw/url not found` — so neither are the
+ * parameters a database error quotes: a line says what happened with an `event` from
+ * `LOG_EVENTS`, and a thrown error is written as its kind and its code.
+ *
+ * Its own logger rather than pino's options, because pino's rule for what to keep would be
+ * three hooks — a log formatter, a bindings formatter and a method hook to drop the message —
+ * whose order is pino's internals; here it is one function, `written`, and a list.
+ */
+/** Most severe first: `fatal` writes the least, `trace` the most. The names are pino's. */
+declare const LOG_LEVELS: readonly ["fatal", "error", "warn", "info", "debug", "trace"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+/** Where lines go: standard output in the server, an array in a test. */
+interface LogSink {
+  write(line: string): unknown;
+}
+/** What `createApp` is told to log: where, and from which level up. */
+interface ServerLogSettings {
+  readonly sink: LogSink;
+  readonly level: LogLevel;
+}
+/** What a background worker complains through. */
+type WorkerLog = Pick<FastifyBaseLogger, 'error'>;
+//#endregion
 //#region src/headers.d.ts
 /**
  * The header a client declares what it was looking at with.
@@ -56,6 +137,11 @@ export declare function sha256(bytes: Buffer): string;
  * the other one.
  */
 export declare const SCHEMA_HASH_HEADER = "x-formancy-schema-hash";
+/**
+ * The token a response is sent with: handed out with the form, and with a draft, naming the id
+ * the response is stored under (0169). Required of an anonymous submission.
+ */
+export declare const SUBMISSION_TOKEN_HEADER = "x-formancy-submission-token";
 //#endregion
 //#region src/app.d.ts
 interface AppOptions {
@@ -97,21 +183,26 @@ interface AppOptions {
   /**
    * Anonymous submissions allowed per IP per minute. Off in tests by setting
    * it high; a real deployment should leave the default.
-   *
-   * NOTE: @fastify/rate-limit's default store is in-memory and therefore
-   * PER PROCESS. Behind more than one replica this counts a fraction of the
-   * traffic and silently permits N times the limit. A multi-replica
-   * deployment must supply a shared store.
    */
   submissionRateLimit?: {
     max: number;
     timeWindowMs: number;
   };
+  /** Where every limit counts; absent, each process counts its own. `main.ts` passes the
+   *  database every replica shares, through `createPostgresRateLimitStore` (0170). */
+  rateLimitStore?: FastifyRateLimitStoreCtor;
   /** Login attempts per IP per minute. Defaults to 10. */
   loginRateLimit?: {
     max: number;
     timeWindowMs: number;
   };
+  /**
+   * The reverse proxies, as addresses and CIDR ranges, whose X-Forwarded-For
+   * names the client every limit above counts. Absent trusts none, so behind a
+   * proxy all respondents share its one budget; `trust-proxy.ts` says why there
+   * is no hop count and no `true`.
+   */
+  trustProxy?: string[];
   /**
    * Largest accepted request body, in bytes. A structural cap BEFORE parsing:
    * the JSON parser should never be handed something enormous in the first
@@ -128,11 +219,29 @@ interface AppOptions {
   /**
    * Largest file this deployment will accept, whatever a form says. A form
    * author sets the per-field limit; this is the operator's ceiling over all
-   * of them, because the disk is theirs. Defaults to 10 MB.
+   * of them, because the disk is theirs. Defaults to 10 MB; a whole number no
+   * larger than `files.size` holds, or `createApp` throws (`upload-settings.ts`).
    */
   maxFileBytes?: number;
   /** Asked about every upload's bytes before they are kept; absent, none is asked (0131). */
   scanner?: Scanner;
+  /**
+   * The deployment's model, which the builders ask through `/model/complete` under the
+   * briefing this server writes. Absent, there is none: `/model` names no provider and no
+   * model, and the admin draws no prompt pane (0165, 0183).
+   */
+  model?: DeploymentModel;
+  /** Model requests per session per minute. Defaults to 10: a run of three turns, three times. */
+  modelRateLimit?: {
+    max: number;
+    timeWindowMs: number;
+  };
+  /**
+   * Where the server's log goes and from which level: a line per request and per error, each
+   * built from a list of fields (`server-log.ts`, 0168). Absent, there is none — `main.ts`
+   * passes one unless `FORMANCY_LOG_LEVEL` is `off`; a host embedding the app chooses (0115).
+   */
+  log?: ServerLogSettings;
 }
 /**
  * The HTTP surface, split into two planes.
@@ -155,6 +264,56 @@ export declare function createApp(storage: Storage, options: AppOptions): Promis
 /** The Storage port over Postgres — the mirror of server-core's in-memory one. */
 export declare function createPostgresStorage(sql: postgres.Sql): Storage;
 //#endregion
+//#region src/postgres-rate-limits.d.ts
+interface PostgresRateLimitOptions {
+  /** {@link COUNT_TIMEOUT_MS} unless a test needs a slow database to be slow sooner. */
+  readonly timeoutMs?: number;
+  /** {@link SWEEP_EVERY_MS} unless a test needs to see a sweep. */
+  readonly sweepEveryMs?: number;
+  /**
+   * The server's log (0168), where the counter says that it stopped answering, that it answers
+   * again and that a sweep failed — each an event from `LOG_EVENTS`, by what was thrown and never
+   * its words, which name the database's address — and where its connections' notices go.
+   * Without one it says nothing, as `createApp` without one keeps no log: a host embedding both
+   * decides.
+   */
+  readonly log?: FastifyBaseLogger;
+}
+/** The counter: a store for `createApp`, and its connections, for whoever made it to end. */
+interface PostgresRateLimits {
+  /** `@fastify/rate-limit`'s store, which `createApp` takes as `rateLimitStore`. */
+  readonly store: FastifyRateLimitStoreCtor;
+  /** Closes the counter's connections, once the app that counts in them is closed. */
+  readonly end: () => Promise<void>;
+}
+/**
+ * `@fastify/rate-limit`'s store over the PostgreSQL every replica already shares (0170).
+ *
+ * The plugin's own store keeps its counts in the process, so behind N replicas each limit
+ * allowed N times what it said. This one keeps them in `rate_limit_counters`, one row per
+ * route and client, and counts with one statement: the upsert takes the row's lock, so two
+ * replicas counting the same client at once are counted one after the other and neither
+ * increment is lost.
+ *
+ * A window starts at a key's first request and lasts the route's `timeWindow`, as the plugin's
+ * own stores do it, on the database's clock — one clock for every replica, where each
+ * process's own would end the window at a different moment on each.
+ *
+ * It opens its own connections from the database's address rather than taking a pool, because
+ * which connections it counts on is what keeps a counter that cannot answer from stopping
+ * everything else: handed the pool storage queries on, it would count correctly and bring that
+ * outage back. A count that does not come back within the bound is abandoned: one still waiting
+ * here to be sent is dropped unsent, and one already sent is ended by the database once it runs,
+ * by the `statement_timeout` of these connections, with no cancel request — a connection more —
+ * needed for it. The error the plugin is handed says nothing about the database, because a route
+ * that refuses without a count sends it to whoever asked; what each route does then is its own
+ * declaration (`rate-limits.ts`).
+ *
+ * The plugin's in-memory store is the second implementation of the same interface, and what
+ * `createApp` counts in when it is given none.
+ */
+export declare function createPostgresRateLimitStore(databaseUrl: string, options?: PostgresRateLimitOptions): PostgresRateLimits;
+//#endregion
 //#region src/db.d.ts
 /**
  * Bootstrap DDL for the thin slice — drizzle-kit migrations arrive with the
@@ -191,7 +350,19 @@ interface CollectorHandle {
 export declare function startFileCollector(storage: Storage, store: FileStore, options?: {
   intervalMs?: number;
   afterHours?: number;
+  log?: WorkerLog;
 }): CollectorHandle;
 //#endregion
-export type { CollectorHandle, FileStore };
+//#region src/completers.d.ts
+/**
+ * The adapter for the provider the operator named (0165): Anthropic through its own SDK,
+ * OpenAI and xAI through OpenAI's, at each one's base URL.
+ *
+ * `fetch` is for the tests, which check where each provider's requests go.
+ */
+export declare function createCompleter(settings: Extract<ModelSettings, {
+  kind: 'configured';
+}>, fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>): Completer;
+//#endregion
+export type { CollectorHandle, DeploymentModel, FileStore, ModelProvider, ModelSettings, PostgresRateLimitOptions, PostgresRateLimits };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/file-store.ts","../src/headers.ts","../src/app.ts","../src/postgres-storage.ts","../src/db.ts","../src/file-collector.ts"],"mappings":";;;;;;;;;;;;;;;;;;;UAoBiB;;EAEf,IAAI,aAAa,OAAO,SAAS;;EAEjC,KAAK,cAAc,QAAQ;;EAE3B,OAAO,cAAc;;EAErB,OAAO,cAAc;;;;;;;;;;;wBAYP,qBAAqB,eAAe;;;;;;;;wBA0DpC,OAAO,OAAO;;;;;;;;;;;qBC1FjB;;;UC6CI;;EAEf;;;;;;EAMA;IAAmB;IAAe;;;;;;;;;;;EAUlC;;;;;;;;;;;;;;EAcA,iBAAiB;;;;;;;;;;EAUjB;IAAwB;IAAa;;;EAErC;IAAmB;IAAa;;;;;;;EAMhC;;;;;;;EAOA,YAAY;;;;;;EAMZ;;EAEA,UAAU;;;;;;;;;;;;;;;;;wBAkBU,UAAU,SAAS,SAAS,SAAS,aAAa,QAAQ;;;;wBC/HhE,sBAAsB,KAAK,SAAS,MAAM;;;;;;;;wBCqIpC,gBAAgB,KAAK,SAAS,MAAM;;;;;;;;;;;;;;;;;;;;;;;;UCrHzC;EACf;;wBAGc,mBACd,SAAS,SACT,OAAO,WACP;EAAW;EAAqB;IAC/B"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/model-settings.ts","../src/routes/model.ts","../src/file-store.ts","../src/server-log.ts","../src/headers.ts","../src/app.ts","../src/postgres-storage.ts","../src/postgres-rate-limits.ts","../src/db.ts","../src/file-collector.ts","../src/completers.ts"],"mappings":";;;;;;;;;;;;;;;qBASa;;KAGD,wBAAwB;KAExB;WACG;;WAEA;WACA,UAAU;WACV;WACA;;KAGV,cAAc,SAAS;;;;;;;;;;;;;;;wBA8BZ,cAAc,KAAK,cAAc;;;;UCrChC;WACN,UAAU;WACV;WACA,WAAW;;;;;;;;;;;;;;;;;;UCCL;;EAEf,IAAI,aAAa,OAAO,SAAS;;EAEjC,KAAK,cAAc,QAAQ;;EAE3B,OAAO,cAAc;;EAErB,OAAO,cAAc;;;;;;;;;;;wBAYP,qBAAqB,eAAe;;;;;;;;wBA0DpC,OAAO,OAAO;;;;;;;;;;;;;;;;;;;;;;cCzEjB;KACD,mBAAmB;;UAKd;EACf,MAAM;;;UAIS;WACN,MAAM;WACN,OAAO;;;KAoRN,YAAY,KAAK;;;;;;;;;;;qBClThB;;;;;qBASA;;;UCgCI;;EAEf;;;;;;EAMA;IAAmB;IAAe;;;;;;;;;;;EAUlC;;;;;;;;;;;;;;EAcA,iBAAiB;;;;;EAKjB;IAAwB;IAAa;;;;EAGrC,iBAAiB;;EAEjB;IAAmB;IAAa;;;;;;;;EAOhC;;;;;;EAMA;;;;;;;EAOA,YAAY;;;;;;;EAOZ;;EAEA,UAAU;;;;;;EAMV,QAAQ;;EAER;IAAmB;IAAa;;;;;;;EAMhC,MAAM;;;;;;;;;;;;;;;;;wBAkBc,UAAU,SAAS,SAAS,SAAS,aAAa,QAAQ;;;;wBC9IhE,sBAAsB,KAAK,SAAS,MAAM;;;UC2BzC;;WAEN;;WAEA;;;;;;;;WAQA,MAAM;;;UAIA;;WAEN,OAAO;;WAEP,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA6BN,6BACd,qBACA,UAAS,2BACR;;;;;;;;wBC8GmB,gBAAgB,KAAK,SAAS,MAAM;;;;;;;;;;;;;;;;;;;;;;;;UC5KzC;EACf;;wBAGc,mBACd,SAAS,SACT,OAAO,WACP;EAAW;EAAqB;EAAqB,MAAM;IAC1D;;;;;;;;;wBCxBa,gBACd,UAAU,QAAQ;EAAiB;IACnC,SAAS,gBAAgB,MAAM,SAAS,OAAO,gBAAgB,QAAQ,YACtE"}

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as bootstrapSchema, i as createPostgresStorage, n as createLocalFileStore, o as createApp, r as sha256, s as SCHEMA_HASH_HEADER, t as startFileCollector } from "./file-collector-CGSJAtGO.mjs";
-export { SCHEMA_HASH_HEADER, bootstrapSchema, createApp, createLocalFileStore, createPostgresStorage, sha256, startFileCollector };
+import { _ as SUBMISSION_TOKEN_HEADER, a as createLocalFileStore, c as createPostgresStorage, g as SCHEMA_HASH_HEADER, i as startFileCollector, l as bootstrapSchema, n as MODEL_PROVIDERS, o as sha256, r as modelSettings, s as createPostgresRateLimitStore, t as createCompleter, u as createApp } from "./completers-C-E2b7Jm.mjs";
+export { MODEL_PROVIDERS, SCHEMA_HASH_HEADER, SUBMISSION_TOKEN_HEADER, bootstrapSchema, createApp, createCompleter, createLocalFileStore, createPostgresRateLimitStore, createPostgresStorage, modelSettings, sha256, startFileCollector };