was-teaching-server 0.9.1

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Library entry point: the surface a downstream composition consumes when this
+ * package is used as a dependency rather than run standalone. Exports the
+ * `fastifyWas` protocol plugin, the community-edition `createApp()`
+ * composition, the
+ * storage pieces a custom backend needs (the `StorageBackend` contract types,
+ * the reference `FileSystemBackend`, and `defaultBackend()`), and the typed
+ * protocol errors a backend or composition throws and handles.
+ *
+ * Importing anything from here also loads the Fastify module augmentation in
+ * types.ts (`FastifyInstance.serverUrl` / `.storage`, `FastifyRequest.zcap`),
+ * so consumers get the decorated instance typed for free.
+ */
+export { fastifyWas, type FastifyWasOptions } from './plugin.js'
+export { createApp } from './server.js'
+export { defaultBackend } from './storage.js'
+export { FileSystemBackend } from './backends/filesystem.js'
+export { PostgresBackend } from './backends/postgres.js'
+export { onboardingTokenAuthorizer } from './provisioning.js'
+export type * from './types.js'
+export * from './errors.js'

package/src/lib/atomicFile.ts

@@ -0,0 +1,176 @@
+/**
+ * Atomic, durable filesystem write helpers, shared by the filesystem backend so
+ * every write goes through one audited path. A durable write must survive a
+ * crash or power loss without leaving a torn (partially-written) or missing
+ * file: bytes land in a temp file in the SAME directory, the file descriptor is
+ * fsync'd before close, the temp is `rename`d (or hard-`link`ed) onto the final
+ * path -- an atomic metadata operation -- and finally the containing directory
+ * is fsync'd so the new directory entry itself is on stable storage.
+ *
+ * Pure and backend-agnostic (no backend imports). Temp files use a `.tmp-`
+ * dot-prefix that no directory enumeration in the tree parses or filters on
+ * (those match `r.`, `.meta.`, `.space.`, `.collection.`, `.policy.`,
+ * `.backend.`, or a `.json` suffix), so a temp file transiently present during
+ * a write is never mistaken for a Resource, sidecar, or config record.
+ */
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import fs from 'node:fs'
+
+const { open, rename, unlink, link } = fs.promises
+
+/**
+ * The temp path a write for `filePath` stages into: a `.tmp-<uuid>` dot-file in
+ * the SAME directory as the target, so the final `rename` / `link` stays on one
+ * filesystem (a cross-device move is not atomic).
+ * @param filePath {string}   the final destination path
+ * @returns {string}
+ */
+export function tempPathFor(filePath: string): string {
+  return path.join(path.dirname(filePath), `.tmp-${randomUUID()}`)
+}
+
+/**
+ * fsync a directory so a just-created/renamed entry within it is durable.
+ * Swallows the errors platforms raise when a directory handle cannot be fsync'd
+ * (e.g. Windows), but lets genuine failures propagate.
+ * @param dirPath {string}
+ * @returns {Promise<void>}
+ */
+export async function fsyncDirectory(dirPath: string): Promise<void> {
+  let handle: fs.promises.FileHandle | undefined
+  try {
+    handle = await open(dirPath, 'r')
+    await handle.sync()
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    // Platforms that cannot fsync a directory handle report one of these; the
+    // rename/link itself already succeeded, so treat directory fsync as a
+    // best-effort durability step rather than a hard failure.
+    if (
+      code === 'EISDIR' ||
+      code === 'EPERM' ||
+      code === 'EBADF' ||
+      code === 'ENOTSUP' ||
+      code === 'EINVAL'
+    ) {
+      return
+    }
+    throw err
+  } finally {
+    await handle?.close()
+  }
+}
+
+/**
+ * Writes `data` to `tempPath` (exclusive create) and fsyncs the file descriptor
+ * before closing, so the bytes are on stable storage before any rename/link
+ * publishes the temp under a caller-visible name.
+ * @param options {object}
+ * @param options.tempPath {string}
+ * @param options.data {string|Buffer}
+ * @returns {Promise<void>}
+ */
+async function writeAndSyncTemp({
+  tempPath,
+  data
+}: {
+  tempPath: string
+  data: string | Buffer
+}): Promise<void> {
+  const handle = await open(tempPath, 'wx')
+  try {
+    await handle.writeFile(data)
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/**
+ * Atomically and durably writes `data` to `filePath` (full replacement):
+ * write + fsync a temp file, `rename` it onto `filePath`, then fsync the
+ * directory. The final path never observes a partially-written file. On any
+ * failure the temp file is cleaned up.
+ * @param options {object}
+ * @param options.filePath {string}
+ * @param options.data {string|Buffer}
+ * @returns {Promise<void>}
+ */
+export async function atomicWriteFile({
+  filePath,
+  data
+}: {
+  filePath: string
+  data: string | Buffer
+}): Promise<void> {
+  const tempPath = tempPathFor(filePath)
+  try {
+    await writeAndSyncTemp({ tempPath, data })
+    await rename(tempPath, filePath)
+  } catch (err) {
+    await unlink(tempPath).catch(() => {})
+    throw err
+  }
+  await fsyncDirectory(path.dirname(filePath))
+}
+
+/**
+ * Atomically and durably creates `filePath`, failing if it already exists --
+ * the `wx`-style create-only semantics, preserved atomically: write + fsync a
+ * temp file, then `fs.promises.link` it onto `filePath` (which rejects with
+ * `EEXIST` when the target exists), unlink the temp, and fsync the directory.
+ * An `EEXIST` propagates so callers can map it to their conflict errors; on any
+ * failure the temp file is cleaned up while `filePath` is left untouched.
+ * @param options {object}
+ * @param options.filePath {string}
+ * @param options.data {string|Buffer}
+ * @returns {Promise<void>}
+ */
+export async function atomicCreateFile({
+  filePath,
+  data
+}: {
+  filePath: string
+  data: string | Buffer
+}): Promise<void> {
+  const tempPath = tempPathFor(filePath)
+  try {
+    await writeAndSyncTemp({ tempPath, data })
+    await link(tempPath, filePath)
+  } catch (err) {
+    // Only ever remove the temp file here, never `filePath`: on an EEXIST the
+    // pre-existing target must survive intact.
+    await unlink(tempPath).catch(() => {})
+    throw err
+  }
+  await unlink(tempPath).catch(() => {})
+  await fsyncDirectory(path.dirname(filePath))
+}
+
+/**
+ * Commits a temp file a caller streamed into (see `tempPathFor`) onto its final
+ * path durably: fsync the temp's bytes, `rename` it onto `filePath`, then fsync
+ * the directory. The caller owns cleanup of the temp file on a streaming
+ * failure (it never reaches here in that case).
+ * @param options {object}
+ * @param options.tempPath {string}
+ * @param options.filePath {string}
+ * @returns {Promise<void>}
+ */
+export async function commitTempFile({
+  tempPath,
+  filePath
+}: {
+  tempPath: string
+  filePath: string
+}): Promise<void> {
+  const handle = await open(tempPath, 'r+')
+  try {
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+  await rename(tempPath, filePath)
+  await fsyncDirectory(path.dirname(filePath))
+}

package/src/lib/backendRegistry.ts

@@ -0,0 +1,139 @@
+/**
+ * Per-Collection backend resolver (spec "Backends"; stage 3 of the BYOS plan).
+ * Maps a Collection's selected `backend.id` to the live `StorageBackend` that
+ * serves its **data plane** (resource bytes, metadata, listings, change feed),
+ * while the server `default` backend (`request.server.storage`) keeps the
+ * **control plane** (Space/Collection descriptions, policies, the backend
+ * registry records). For the `default` backend the two planes are the same
+ * instance, so behavior is byte-for-byte unchanged.
+ *
+ * `resolveBackend` short-circuits to the default backend for the common
+ * `default`/absent selection (one branch, no extra I/O). For a Collection that
+ * selects a registered `external` backend it loads the (secret-bearing) backend
+ * record from the control plane and builds -- memoized -- the provider adapter
+ * from the injected `backendProviders` registry; with no factory for the record's
+ * `provider` it fails closed with `unsupported-backend` (409). Memoization
+ * mirrors spaceContext.ts: one `LruCache` per registry (a `WeakMap`), so adapter
+ * instances are reused across requests and a registry's adapters are GC'd with
+ * it.
+ */
+import type { FastifyRequest } from 'fastify'
+import { LruCache } from '@interop/lru-memoize'
+import { DEFAULT_BACKEND_ID } from './backends.js'
+import { UnsupportedBackendError } from '../errors.js'
+import { RESOLVED_BACKEND_CACHE_MAX } from '../config.default.js'
+import type {
+  BackendProviderRegistry,
+  CollectionDescription,
+  StorageBackend
+} from '../types.js'
+
+/**
+ * One adapter cache per provider registry, keyed by `${spaceId}/${backendId}`.
+ * Scoped to the registry instance via a `WeakMap` (rather than module-global) so
+ * parallel test suites never share adapters, and a cache is discarded with its
+ * registry. `memoize` evicts a rejected promise automatically, so a failed
+ * resolution (missing record / no factory) is retried on the next request rather
+ * than cached.
+ */
+const adapterCaches = new WeakMap<BackendProviderRegistry, LruCache>()
+
+/**
+ * Returns the (lazily created) adapter cache for a provider registry.
+ * @param providers {BackendProviderRegistry}
+ * @returns {LruCache}
+ */
+function adapterCacheFor(providers: BackendProviderRegistry): LruCache {
+  let cache = adapterCaches.get(providers)
+  if (!cache) {
+    cache = new LruCache({ max: RESOLVED_BACKEND_CACHE_MAX })
+    adapterCaches.set(providers, cache)
+  }
+  return cache
+}
+
+/**
+ * Resolves the data-plane `StorageBackend` for a Collection. Returns the server
+ * default backend when the Collection selects `default` (or selects nothing);
+ * otherwise builds (memoized) the provider adapter for its registered backend.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server` (the
+ *   control-plane `storage`, the `backendProviders` registry, and the
+ *   non-request instance `log` passed to the memoized adapter factory)
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param [options.collectionDescription] {CollectionDescription}   the
+ *   already-fetched description (most handlers fetch it for auth); read from the
+ *   control plane when omitted
+ * @returns {Promise<StorageBackend>}
+ */
+export async function resolveBackend({
+  request,
+  spaceId,
+  collectionId,
+  collectionDescription
+}: {
+  request: FastifyRequest
+  spaceId: string
+  collectionId: string
+  collectionDescription?: CollectionDescription
+}): Promise<StorageBackend> {
+  const { storage, backendProviders } = request.server
+  const description =
+    collectionDescription ??
+    (await storage.getCollectionDescription({ spaceId, collectionId }))
+  const backendId = description?.backend?.id
+  // Fast path: the default backend is both control and data plane (unchanged).
+  if (backendId === undefined || backendId === DEFAULT_BACKEND_ID) {
+    return storage
+  }
+  return adapterCacheFor(backendProviders).memoize<StorageBackend>({
+    key: `${spaceId}/${backendId}`,
+    fn: async () => {
+      // Control-plane read: the secret-bearing record lives on the default backend.
+      const record = await storage.getBackend({ spaceId, backendId })
+      if (!record) {
+        throw new UnsupportedBackendError({ backendId })
+      }
+      // Status gating is deferred (stage 4): the resolver keys on whether a
+      // provider factory is registered, not on `connection.status` (which only
+      // becomes `connected` once the OAuth exchange exists).
+      const factory = backendProviders.get(record.provider)
+      if (!factory) {
+        throw new UnsupportedBackendError({
+          backendId,
+          detail: `Backend '${backendId}' is registered but not connected/operable yet.`
+        })
+      }
+      // Wire the non-request instance logger (as `createApp` does for the
+      // primary backend), NOT `request.log`: the adapter is memoized and reused
+      // across requests, so capturing the first request's per-request child
+      // logger would mis-tag every later log line with that first request's id.
+      return factory(record, { logger: request.server.log })
+    }
+  })
+}
+
+/**
+ * Drops the memoized adapter for a backend record. Call after a record changes
+ * (register-replace / deregister) so the next resolve rebuilds the adapter from
+ * the new connection material.
+ * @param options {object}
+ * @param options.providers {BackendProviderRegistry}
+ * @param options.spaceId {string}
+ * @param options.backendId {string}
+ * @returns {void}
+ */
+export function invalidateResolvedBackend({
+  providers,
+  spaceId,
+  backendId
+}: {
+  providers: BackendProviderRegistry
+  spaceId: string
+  backendId: string
+}): void {
+  // Only touch a cache that already exists for this registry.
+  adapterCaches.get(providers)?.delete(`${spaceId}/${backendId}`)
+}

package/src/lib/backendUsage.ts

@@ -0,0 +1,79 @@
+/**
+ * Backend-agnostic derivation of the quota-report condition fields (spec
+ * "Quotas"). Both storage backends build their `BackendUsage` entries through
+ * this helper so the `state` / `limit` / `restrictedActions` thresholds cannot
+ * drift between them; only the usage *measurement* (a `du` pass vs a
+ * transactional counter) is backend-specific.
+ */
+import { QUOTA_NEAR_LIMIT_FRACTION } from '../config.default.js'
+import type {
+  Action,
+  BackendState,
+  BackendUsage,
+  StorageLimit
+} from '../types.js'
+
+/**
+ * Builds the backend-identity and condition fields shared by the Space and
+ * per-Collection quota reports. `usageBytes` is what the report shows (the
+ * Space total or a single Collection's slice); `spaceTotalBytes` drives the
+ * `state` / `restrictedActions`, which are backend-wide (the quota is a
+ * per-Space limit) and so always measured against the Space total. The
+ * `constraints.maxUploadBytes` cap is advertised when configured.
+ * @param options {object}
+ * @param options.usageBytes {number}   the usage figure to report
+ * @param options.spaceTotalBytes {number}   the Space total, for state
+ * @param [options.capacityBytes] {number}   the configured per-Space limit
+ * @param [options.maxUploadBytes] {number}   the per-upload cap to advertise
+ * @param options.id {string}   the backend's id (from `describe()`)
+ * @param [options.name] {string}   the backend's display name
+ * @param options.managedBy {string}   the backend's custody mode
+ * @returns {Omit<BackendUsage, 'measuredAt' | 'usageByCollection'>}
+ */
+export function backendUsageFields({
+  usageBytes,
+  spaceTotalBytes,
+  capacityBytes,
+  maxUploadBytes,
+  id,
+  name,
+  managedBy
+}: {
+  usageBytes: number
+  spaceTotalBytes: number
+  capacityBytes?: number
+  maxUploadBytes?: number
+  id: string
+  name?: string
+  managedBy: BackendUsage['managedBy']
+}): Omit<BackendUsage, 'measuredAt' | 'usageByCollection'> {
+  const limit: StorageLimit =
+    capacityBytes === undefined
+      ? { isUnlimited: true }
+      : { capacityBytes, isUnlimited: false }
+
+  let state: BackendState = 'ok'
+  let restrictedActions: Action[] = []
+  if (capacityBytes !== undefined) {
+    if (spaceTotalBytes >= capacityBytes) {
+      state = 'over-quota'
+      // The backend is full: writes are restricted, reads/deletes still work.
+      restrictedActions = ['POST', 'PUT']
+    } else if (spaceTotalBytes >= capacityBytes * QUOTA_NEAR_LIMIT_FRACTION) {
+      state = 'near-limit'
+    }
+  }
+
+  return {
+    id,
+    ...(name !== undefined && { name }),
+    managedBy,
+    state,
+    usageBytes,
+    limit,
+    ...(maxUploadBytes !== undefined && {
+      constraints: { maxUploadBytes }
+    }),
+    restrictedActions
+  }
+}