@venturekit/data 0.0.31 → 0.0.33

package/src/sql/vk_data_004_file_object.sql

@@ -0,0 +1,112 @@
+-- @venturekit/data — uploaded-object metadata.
+--
+-- Table created by this migration:
+--   vk_file_object — the row that makes an S3 object findable and deletable
+--
+-- Backs `@venturekit/data/files`.
+--
+-- # Why a table when @venturekit/storage already talks to S3
+--
+-- That package is complete on the object: put, get, head, presign, copy, list,
+-- image optimisation. What a bucket cannot tell you is anything a product needs
+-- to know about an upload — which tenant owns it, what it is for, who put it
+-- there, whether the same bytes are already stored, and when it may be deleted.
+-- `ListObjectsV2` plus a key-naming convention is the usual substitute, and it
+-- fails the first time somebody needs "every document for this tenant, newest
+-- first" or a retention rule that differs per purpose.
+--
+-- # The deletion order is the point
+--
+-- Rows are never hard-deleted on the request path. `archived_at` is set, and a
+-- retention sweep removes the object and the row together — but "together" is
+-- not available: there is no transaction spanning S3 and Postgres, so one of the
+-- two failure modes has to be chosen deliberately.
+--
+--   * row first, then object → an orphaned object nobody can account for. Only
+--     discoverable by diffing the entire bucket against this table.
+--   * object first, then row → a row naming a key that 404s. Discoverable by
+--     walking rows, which is cheap, and invisible to users anyway because the
+--     row is already archived.
+--
+-- So the sweep deletes objects first and rows second, and a crash in between
+-- leaves the recoverable state rather than the silent one. `sweepArchivedFiles`
+-- is re-runnable for exactly this reason.
+--
+-- Additive for existing projects: one new table, no existing file edited, and
+-- nothing writes to it until a project calls `recordFileObject()`.
+
+CREATE TABLE IF NOT EXISTS vk_file_object (
+  id            uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- NULL for platform-wide artefacts belonging to no tenant. No foreign key:
+  -- the table a tenant lives in is the consumer's, and `vk_tenants` only exists
+  -- with @venturekit-pro/tenancy installed.
+  tenant_id     uuid,
+
+  -- What the file is FOR, which is what decides its retention and who may read
+  -- it. Free text rather than an enum because the vocabulary is the product's —
+  -- 'student_photo' carries obligations 'report_artefact' does not, and only the
+  -- consumer knows which of theirs is which.
+  purpose       text        NOT NULL,
+
+  -- Stored, not derived: the bucket changes per stage and per region, and a row
+  -- written in one stage must stay resolvable after a restore into another.
+  bucket        text        NOT NULL,
+  object_key    text        NOT NULL,
+
+  content_type  text        NOT NULL,
+  size_bytes    bigint      NOT NULL CHECK (size_bytes >= 0),
+
+  -- SHA-256 hex. Lets a re-upload of identical bytes be recognised instead of
+  -- duplicated, and lets a restore be verified.
+  checksum      char(64),
+
+  -- The name the user's file had. Never the storage key: a key built from user
+  -- input is a path-traversal question and a collision waiting to happen.
+  original_name text,
+  uploaded_by   uuid,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+
+  -- Soft delete. Set on the request path; the retention sweep is what actually
+  -- removes the object and then this row.
+  archived_at   timestamptz,
+
+  -- One row per object. A second row for the same key would mean two records
+  -- claiming one set of bytes, and archiving either would delete the object out
+  -- from under the other.
+  CONSTRAINT vk_file_object_bucket_key_uniq UNIQUE (bucket, object_key)
+);
+
+-- "Every live file for this tenant, of this purpose, newest first" — the query
+-- the table exists for. Partial, so archived rows do not bloat it.
+CREATE INDEX IF NOT EXISTS vk_file_object_tenant_purpose_idx
+  ON vk_file_object (tenant_id, purpose, created_at DESC)
+  WHERE archived_at IS NULL;
+
+-- De-duplication on re-upload: same bytes, same tenant, already stored.
+CREATE INDEX IF NOT EXISTS vk_file_object_checksum_idx
+  ON vk_file_object (tenant_id, checksum)
+  WHERE archived_at IS NULL AND checksum IS NOT NULL;
+
+-- The retention sweep's claim.
+CREATE INDEX IF NOT EXISTS vk_file_object_archived_idx
+  ON vk_file_object (archived_at)
+  WHERE archived_at IS NOT NULL;
+
+-- # On row-level security
+--
+-- No policy is installed here, because `vk_install_tenant_guards()` needs the
+-- name of the consumer's application role and this migration cannot know it. A
+-- project that wants RLS on this table should call the installer itself:
+--
+--   SELECT vk_install_tenant_guards('public', 'vk_file_object', 'app_user');
+--
+-- Until then, reads that serve a request must carry the scope predicate, which
+-- `listFileObjects()` and `findFileObjectByChecksum()` do by default.
+
+COMMENT ON TABLE vk_file_object IS
+  'Metadata for an object in S3. The bytes live in the bucket; this row is what makes them findable, attributable and deletable. See @venturekit/data/files.';
+COMMENT ON COLUMN vk_file_object.archived_at IS
+  'Soft delete. The retention sweep deletes the OBJECT first and then this row, so a crash leaves a recoverable dangling row rather than an unaccountable orphaned object.';