server/app_backend.ts

App backend types and factory — database initialization + auth migrations + deps.

Provides AppBackend, CreateAppBackendOptions, and create_app_backend().

Vocabulary: - AppDeps — stateless capabilities: injectable, swappable per environment - *Options — static values set at startup, per-factory configuration - Runtime state — mutable values (e.g., bootstrap_status) — NOT in deps or options

Declarations
#

3 declarations

view source

AppBackend
#

server/app_backend.ts view source

AppBackend

Result of create_app_backend() — database metadata + deps bundle.

This is the initialized backend, not the HTTP server. Pass it to create_app_server() to assemble the Hono app.

deps

type AppDeps

db_type

type DbType

db_name

type string

migration_results

Migration results from create_app_backend — auth migrations plus any consumer namespaces passed via migration_namespaces.

type ReadonlyArray<MigrationResult>
readonly

close

Close the database connection. Bound to the actual driver.

type () => Promise<void>

create_app_backend
#

server/app_backend.ts view source

(options: CreateAppBackendOptions): Promise<AppBackend>

Initialize the backend: database + auth migrations + deps.

Calls create_db → run_migrations (auth namespace, then any migration_namespaces from options in order) and bundles the result with the provided keyring and password deps.

options

keyring, password deps, optional database URL, and optional migration_namespaces

type CreateAppBackendOptions

returns

Promise<AppBackend>

app backend with deps, database metadata, and combined migration results

throws

  • Error - if `migration_namespaces` contains a namespace in `RESERVED_MIGRATION_NAMESPACES`

CreateAppBackendOptions
#

server/app_backend.ts view source

CreateAppBackendOptions

Input for create_app_backend().

keyring is passed pre-validated — callers handle their own error reporting (e.g., tx uses runtime.exit(1) on invalid keys).

stat

Get file/directory stats, or null if path doesn't exist.

type (path: string) => Promise<StatResult | null>

read_text_file

Read a file as text.

type (path: string) => Promise<string>

delete_file

Delete a file.

type (path: string) => Promise<void>

database_url

Database connection URL (postgres://, file://, or memory://).

type string

keyring

Validated cookie signing keyring.

type Keyring

password

Password hashing implementation. Use argon2_password_deps in production.

type PasswordHashDeps

log

Structured logger instance. Omit for default (new Logger('server')).

type Logger

on_audit_event

Initial subscriber appended to AppDeps.audit.on_event_chain. Use to broadcast audit events via SSE / WS. Additional subscribers (e.g. the factory-managed audit-log SSE) are appended at server assembly via audit.on_event_chain.push(listener) — no shallow-copy of AppDeps required.

type (event: AuditLogEvent) => void

audit_log_config

Audit-log config for consumer event-type extensions. Built once at startup via create_audit_log_config({extra_events}) and captured inside AppDeps.audit so consumer handlers cannot silently fall back to the builtin config. Omit to use BUILTIN_AUDIT_LOG_CONFIG (no extra events).

type AuditLogConfig

migration_namespaces

Additional migration namespaces to run after the builtin auth namespace. The shared schema_version table records one row per applied migration (namespace, name, sequence); order is append-only so forward-only guarantees hold per-namespace.

Names in RESERVED_MIGRATION_NAMESPACES (currently ['fuz_auth']) are rejected at startup. Omit for no extra namespaces. This is the only place to splice consumer migrations — DB init belongs to the backend lifecycle, not server assembly.

type ReadonlyArray<MigrationNamespace>

Depends on
#