was-teaching-server 0.9.1 → 0.11.0

package/src/backends/postgresSchema.ts

@@ -21,7 +21,7 @@ import type pg from 'pg'
  * never edit an applied entry.
  */
 export const MIGRATIONS: string[] = [
-  // v1: the full WAS + WebKMS surface.
+  // v1: the full WAS + WebKMS + chunked-storage surface.
   `
   -- The Spaces tree. 'description' is NULL for a placeholder row created by a
   -- write below the Space level (a resource/policy write to a Space whose
@@ -29,17 +29,29 @@ export const MIGRATIONS: string[] = [
   -- without a '.space.' file; getSpaceDescription treats it as absent.
   -- 'usage_bytes' is the transactional quota counter (spec "Quotas"),
   -- maintained in the same transaction as every content write and delete.
+  -- 'controller' denormalizes the Space controller (also present as
+  -- description->>'controller') onto its own indexed column, keeping the
+  -- per-controller COUNT(*) for the Spaces count quota cheap and lockable;
+  -- writeSpace maintains it on every insert and update.
   CREATE TABLE spaces (
     space_id    text COLLATE "C" PRIMARY KEY,
     description jsonb,
-    usage_bytes bigint NOT NULL DEFAULT 0
+    usage_bytes bigint NOT NULL DEFAULT 0,
+    controller  text
   );
+  CREATE INDEX spaces_controller_idx ON spaces (controller);
 
+  -- 'description_version' is the monotonic Collection Description version --
+  -- the ETag validator behind conditional (If-Match) Collection Description
+  -- writes, so concurrent recipient edits compare-and-swap instead of
+  -- clobbering. Kept out of the stored 'description' jsonb (it travels only
+  -- as the ETag header); writeCollection bumps it on every write.
   CREATE TABLE collections (
-    space_id      text COLLATE "C" NOT NULL
-                  REFERENCES spaces ON DELETE CASCADE,
-    collection_id text COLLATE "C" NOT NULL,
-    description   jsonb,
+    space_id            text COLLATE "C" NOT NULL
+                        REFERENCES spaces ON DELETE CASCADE,
+    collection_id       text COLLATE "C" NOT NULL,
+    description         jsonb,
+    description_version integer NOT NULL DEFAULT 1,
     PRIMARY KEY (space_id, collection_id)
   );
 
@@ -49,6 +61,15 @@ export const MIGRATIONS: string[] = [
   -- 'content_type' records the last-known type on a tombstone. 'version' /
   -- 'meta_version' are the two ETag validators; 'custom' is the user-writable
   -- metadata (or the opaque encryption envelope on an encrypted Collection).
+  -- 'created_by' is the Resource's creator -- the DID of the invoker of its
+  -- FIRST content write, set once and preserved verbatim thereafter (the
+  -- spec's OPTIONAL 'createdBy'); NULL for a row written by a caller with no
+  -- resolved invoker. 'epoch' is the client-declared key epoch the content
+  -- was encrypted under (multi-recipient encrypted Collections), stored
+  -- opaquely (the server never computes or verifies it); NULL when no epoch
+  -- was declared (a plaintext Collection, or an encrypted write that omitted
+  -- the stamp). Neither is COLLATE "C": unlike 'created_at' / 'updated_at',
+  -- they never participate in an ORDER BY or keyset comparison.
   CREATE TABLE resources (
     space_id      text COLLATE "C" NOT NULL,
     collection_id text COLLATE "C" NOT NULL,
@@ -63,6 +84,8 @@ export const MIGRATIONS: string[] = [
     deleted       boolean NOT NULL DEFAULT false,
     created_at    text COLLATE "C" NOT NULL,
     updated_at    text COLLATE "C" NOT NULL,
+    created_by    text,
+    epoch         text,
     PRIMARY KEY (space_id, collection_id, resource_id),
     FOREIGN KEY (space_id, collection_id)
       REFERENCES collections ON DELETE CASCADE
@@ -73,6 +96,30 @@ export const MIGRATIONS: string[] = [
   CREATE INDEX resources_changes_idx
     ON resources (space_id, collection_id, updated_at, resource_id);
 
+  -- Chunk storage for chunked Resources. One row per addressed chunk
+  -- (space, collection, resource, index); 'bytes' is the opaque chunk
+  -- representation (stored exactly like a binary Resource's content, never
+  -- parsed), 'size' its byte length (the quota-counter input), and 'version'
+  -- the chunk's own monotonic ETag validator (independent of the parent
+  -- Resource's). The foreign key to 'resources' gives chunk rows the same
+  -- ON DELETE CASCADE the Space/Collection tree already uses, so a HARD
+  -- delete of the parent Resource (or its Collection or Space) removes its
+  -- chunks with it; a SOFT delete (the tombstone UPDATE in deleteResource)
+  -- removes them explicitly in the same transaction instead.
+  CREATE TABLE chunks (
+    space_id      text COLLATE "C" NOT NULL,
+    collection_id text COLLATE "C" NOT NULL,
+    resource_id   text COLLATE "C" NOT NULL,
+    chunk_index   integer NOT NULL,
+    content_type  text NOT NULL,
+    bytes         bytea NOT NULL,
+    size          bigint NOT NULL DEFAULT 0,
+    version       integer NOT NULL,
+    PRIMARY KEY (space_id, collection_id, resource_id, chunk_index),
+    FOREIGN KEY (space_id, collection_id, resource_id)
+      REFERENCES resources ON DELETE CASCADE
+  );
+
   -- Policies for all three levels in one table; '' sentinel columns keep the
   -- primary key total (Postgres PKs reject NULL). Space policy: ('', '');
   -- collection policy: (cid, ''); resource policy: (cid, rid).
@@ -94,6 +141,22 @@ export const MIGRATIONS: string[] = [
     PRIMARY KEY (space_id, backend_id)
   );
 
+  -- Space-scoped zcap revocations -- the WAS route families' sibling of the
+  -- keystore-scoped 'revocations' table below. A separate table (rather than
+  -- a nullable-FK union over one table) lets each keep its own
+  -- ON DELETE CASCADE to its parent and its own composite primary key;
+  -- deleting a Space here deletes its revocations. Columns mirror
+  -- 'revocations', with 'space_id' referencing the spaces tree in place of
+  -- 'keystore_id'.
+  CREATE TABLE space_revocations (
+    space_id      text COLLATE "C" NOT NULL REFERENCES spaces ON DELETE CASCADE,
+    delegator     text COLLATE "C" NOT NULL,
+    capability_id text COLLATE "C" NOT NULL,
+    record        jsonb NOT NULL,
+    expires       text COLLATE "C",
+    PRIMARY KEY (space_id, delegator, capability_id)
+  );
+
   -- WebKMS facet: a sibling tree to spaces, exactly as on the filesystem.
   -- 'controller' / 'sequence' / 'kms_module' are denormalized from the
   -- verbatim config for the list filter and the update gates.
@@ -126,57 +189,6 @@ export const MIGRATIONS: string[] = [
     expires       text COLLATE "C",
     PRIMARY KEY (keystore_id, delegator, capability_id)
   );
-  `,
-  // v2: denormalize a Space's controller onto its own column for the Spaces
-  // count quota (spec "Quotas"). The controller also lives inside 'description'
-  // (description->>'controller'), but a dedicated, indexed column keeps the
-  // per-controller COUNT(*) cheap and lockable. Backfill from existing rows;
-  // writeSpace maintains it on every insert and update.
-  `
-  ALTER TABLE spaces ADD COLUMN controller text;
-  UPDATE spaces SET controller = description->>'controller';
-  CREATE INDEX spaces_controller_idx ON spaces (controller);
-  `,
-  // v3: record a Resource's creator -- the DID of the invoker of its FIRST
-  // content write, set once and preserved verbatim thereafter (the spec's
-  // OPTIONAL `createdBy`). NULL for a pre-existing row and for one written by
-  // a caller with no resolved invoker. Not `COLLATE "C"`: unlike `created_at` /
-  // `updated_at`, this column never participates in an `ORDER BY` or keyset
-  // comparison.
-  `
-  ALTER TABLE resources ADD COLUMN created_by text;
-  `,
-  // v4: Space-scoped zcap revocations -- the WAS route families' sibling of the
-  // keystore-scoped `revocations` table above. A separate table (rather than a
-  // nullable-FK union over one table) lets each keep its own `ON DELETE CASCADE`
-  // to its parent and its own composite primary key; deleting a Space here
-  // deletes its revocations. Columns mirror `revocations`, with 'space_id'
-  // referencing the spaces tree in place of 'keystore_id'.
-  `
-  CREATE TABLE space_revocations (
-    space_id      text COLLATE "C" NOT NULL REFERENCES spaces ON DELETE CASCADE,
-    delegator     text COLLATE "C" NOT NULL,
-    capability_id text COLLATE "C" NOT NULL,
-    record        jsonb NOT NULL,
-    expires       text COLLATE "C",
-    PRIMARY KEY (space_id, delegator, capability_id)
-  );
-  `,
-  // v5: the client-declared key epoch a Resource's content was encrypted under
-  // (multi-recipient encrypted Collections). Stored opaquely: the server never
-  // computes or verifies it. NULL when no epoch was declared (a plaintext
-  // Collection, or an encrypted write that omitted the stamp). Not `COLLATE "C"`
-  // -- it never participates in an `ORDER BY` or keyset comparison.
-  `
-  ALTER TABLE resources ADD COLUMN epoch text;
-  `,
-  // v6: the monotonic Collection Description version -- the ETag validator behind
-  // conditional (`If-Match`) Collection Description writes, so concurrent
-  // recipient edits compare-and-swap instead of clobbering. Kept out of the
-  // stored 'description' jsonb (it travels only as the `ETag` header). Backfill
-  // existing rows to 1; writeCollection bumps it on every write.
-  `
-  ALTER TABLE collections ADD COLUMN description_version integer NOT NULL DEFAULT 1;
   `
 ]
 

package/src/errors.ts

@@ -124,6 +124,25 @@ export class InvalidResourceIdError extends ProblemError {
   }
 }
 
+/**
+ * 400 — the `:chunkIndex` path param of a chunk operation (the
+ * `chunked-streams` feature) is not a canonical non-negative integer. The
+ * canonical-form requirement (no leading zeros, no sign) keeps every chunk
+ * addressable at exactly one URL.
+ * @param options {object}
+ * @param [options.requestName] {string}   request name used in the error title
+ */
+export class InvalidChunkIndexError extends ProblemError {
+  constructor({ requestName }: { requestName?: string } = {}) {
+    super({
+      type: ProblemTypes.INVALID_ID,
+      title: `Invalid ${requestName || 'Chunk'} request`,
+      detail: 'Invalid chunk index (must be a canonical non-negative integer).',
+      statusCode: 400
+    })
+  }
+}
+
 /**
  * 409 — a `POST` create operation supplied an `id` that already exists.
  * Create-or-replace at a client-chosen id is the idempotent `PUT` path, which
@@ -146,26 +165,39 @@ export class IdConflictError extends ProblemError {
 }
 
 /**
- * 409 — a Resource write carries an `indexed` blinded attribute marked
- * `unique: true` whose (HMAC key id, name, value) triple is already claimed by
- * another live Resource in the same Collection (the EDV unique-attribute
- * invariant, enforced by backends carrying the `blinded-index-query` feature).
- * Reuses the `id-conflict` problem type (like the WebKMS conflicts): a unique
- * blinded attribute is a client-chosen identifier-like claim, and the registry
- * defines no more specific kind. Only ever observable by a caller already
- * authorized to write the target.
+ * 409 — a write claims a `unique: true` indexed attribute already claimed by
+ * another live Resource in the same Collection. Two invariants share it: the
+ * EDV blinded one (an `indexed` blinded attribute's (HMAC key id, name, value)
+ * triple; the `blinded-index-query` feature, `variant: 'blinded'`, the
+ * default) and the plaintext equality one (a `unique`-declared `indexes`
+ * attribute's (name, value) pair; the `equality-query` feature,
+ * `variant: 'equality'`). Reuses the `id-conflict` problem type (like the
+ * WebKMS conflicts): a unique attribute is a client-chosen identifier-like
+ * claim, and the registry defines no more specific kind. Only ever observable
+ * by a caller already authorized to write the target.
  */
 export class UniqueAttributeConflictError extends ProblemError {
-  constructor() {
+  constructor({
+    variant = 'blinded'
+  }: { variant?: 'blinded' | 'equality' } = {}) {
+    const attribute =
+      variant === 'equality'
+        ? 'unique indexed attribute'
+        : 'unique blinded index attribute'
     const detail =
-      'Could not write document; a unique blinded index attribute is already' +
+      `Could not write document; a ${attribute} is already` +
       ' in use by another Resource in this Collection.'
     super({
       type: ProblemTypes.ID_CONFLICT,
-      title: 'A unique blinded index attribute is already in use.',
+      title: `A ${attribute} is already in use.`,
       detail,
       statusCode: 409,
-      problems: [{ detail, pointer: '#/indexed' }]
+      problems: [
+        {
+          detail,
+          pointer: variant === 'equality' ? '#/indexes' : '#/indexed'
+        }
+      ]
     })
   }
 }