was-teaching-server 0.9.1 → 0.11.0

package/src/lib/importTar.ts

@@ -2,7 +2,11 @@ import * as tar from 'tar-stream'
 import YAML from 'yaml'
 import type { Readable } from 'node:stream'
 import { assertValidId } from './validateId.js'
-import { parseResourceFileName } from './resourceFileName.js'
+import {
+  parseChunkDirName,
+  parseChunkIndexSegment,
+  parseResourceFileName
+} from './resourceFileName.js'
 import { InvalidImportError } from '../errors.js'
 import type {
   CollectionDescription,
@@ -53,6 +57,60 @@ export function metaSidecarFileId(fileName: string): string | undefined {
   return dotFileId(fileName, META_PREFIX)
 }
 
+/**
+ * If `fileName` is a chunk entry relative to its Collection dir
+ * (`.chunks.<encodedResourceId>/<chunkFile>`, the `chunked-streams` feature),
+ * returns the parent `resourceId` (decoded from the directory name) and the
+ * `chunkFileName` (its single-segment basename inside the chunk directory);
+ * otherwise undefined. Any deeper nesting or a traversal segment in the chunk
+ * file name is rejected (undefined), so the caller never builds a path from it.
+ * @param fileName {string}   the entry name relative to the Collection dir
+ * @returns {{ resourceId: string, chunkFileName: string } | undefined}
+ */
+function chunkEntryName(
+  fileName: string
+): { resourceId: string; chunkFileName: string } | undefined {
+  const slash = fileName.indexOf('/')
+  if (slash === -1) {
+    return undefined
+  }
+  const resourceId = parseChunkDirName(fileName.slice(0, slash))
+  if (resourceId === undefined) {
+    return undefined
+  }
+  const chunkFileName = fileName.slice(slash + 1)
+  if (
+    chunkFileName.length === 0 ||
+    chunkFileName.includes('/') ||
+    chunkFileName === '..'
+  ) {
+    return undefined
+  }
+  return { resourceId, chunkFileName }
+}
+
+/**
+ * The canonical-chunk-index gate for an archive chunk file: returns true only
+ * when `chunkFileName` is a chunk representation (`r.<index>.<encType>.<ext>`)
+ * or its version sidecar (`.meta.<index>.json`) whose RAW `<index>` segment
+ * passes {@link parseChunkIndexSegment} -- the same predicate the live route
+ * enforces. Validating the raw (undecoded) segment rejects both non-canonical
+ * spellings (`r.01.*`, which would alias chunk 1) and percent-encoded ones
+ * (`r.%31.*`), so an imported chunk file is always reachable at exactly the
+ * URL the listing advertises. Anything else in a chunk directory is dropped.
+ * @param chunkFileName {string}   the file's basename inside the chunk dir
+ * @returns {boolean}
+ */
+function isCanonicalChunkFileName(chunkFileName: string): boolean {
+  const indexSegment =
+    metaSidecarFileId(chunkFileName) ??
+    (chunkFileName.startsWith('r.') ? chunkFileName.split('.')[1] : undefined)
+  return (
+    indexSegment !== undefined &&
+    parseChunkIndexSegment(indexSegment) !== undefined
+  )
+}
+
 /** One extracted archive entry, keyed by its archive path. */
 export interface TarEntry {
   type: 'file' | 'directory'
@@ -66,6 +124,19 @@ export interface ImportPlanResource {
   body: Buffer
 }
 
+/**
+ * One chunk file of a chunked Resource staged for import (the `chunked-streams`
+ * feature): the raw bytes carried verbatim, keyed by the parent `resourceId`
+ * (decoded from the `.chunks.<encId>/` directory name) and the chunk file's
+ * basename inside that directory (`r.<index>...` bytes or its `.meta.<index>.json`
+ * version sidecar).
+ */
+export interface ImportPlanChunkFile {
+  resourceId: string
+  fileName: string
+  body: Buffer
+}
+
 /** One collection (plus its resources and policies) staged for import. */
 export interface ImportPlanCollection {
   collectionId: string
@@ -77,6 +148,8 @@ export interface ImportPlanCollection {
   resourcePolicies: Map<string, PolicyDocument>
   /** Resource metadata sidecars (raw `.meta.<id>.json` bytes), keyed by resourceId. */
   resourceMetadata: Map<string, Buffer>
+  /** Chunk files of chunked Resources in this Collection, carried verbatim. */
+  chunkFiles: ImportPlanChunkFile[]
 }
 
 /** The merge plan produced by {@link buildImportPlan}. */
@@ -185,10 +258,12 @@ export function validateManifest(entries: Map<string, TarEntry>): void {
  * - space/<sourceSpaceId>/<collectionId>/.policy.<collectionId>.json (collection policy)
  * - space/<sourceSpaceId>/<collectionId>/.policy.<resourceId>.json (resource policy)
  * - space/<sourceSpaceId>/<collectionId>/r.<resourceId>.<encodedContentType>.<ext>
+ * - space/<sourceSpaceId>/<collectionId>/.chunks.<encodedResourceId>/<chunkFile>
+ *   (a chunked Resource's chunk files; the `chunked-streams` feature)
  *
  * The source space id in the path may differ from the import target; collection
- * metadata, r.* resource files, and `.policy.*` policy files are merged into the
- * destination.
+ * metadata, r.* resource files, `.chunks.*` chunk files, and `.policy.*` policy
+ * files are merged into the destination.
  *
  * @param entries {Map<string, TarEntry>}
  * @returns {ImportPlan}
@@ -246,6 +321,7 @@ export function buildImportPlan(entries: Map<string, TarEntry>): ImportPlan {
     let collectionPolicy: PolicyDocument | undefined
     const resourcePolicies = new Map<string, PolicyDocument>()
     const resourceMetadata = new Map<string, Buffer>()
+    const chunkFiles: ImportPlanChunkFile[] = []
     for (const [entryName, entry] of entries) {
       if (
         !entryName.startsWith(collectionPrefix) ||
@@ -256,6 +332,32 @@ export function buildImportPlan(entries: Map<string, TarEntry>): ImportPlan {
       }
 
       const fileName = entryName.slice(collectionPrefix.length)
+
+      // Chunk files of a chunked Resource live in a per-Resource subdirectory
+      // (`.chunks.<encId>/<chunkFile>`), so they are the one Collection entry
+      // carrying a slash. Carry them verbatim, keyed by the parent resourceId
+      // decoded from the directory name (validated against path traversal).
+      const chunk = chunkEntryName(fileName)
+      if (chunk) {
+        assertValidId(chunk.resourceId, {
+          kind: 'resource',
+          requestName: 'Import Space'
+        })
+        // Drop a chunk file with a non-canonical index (or a stray file that
+        // is neither a representation nor a sidecar): written verbatim it
+        // would be unreachable at the canonical member URL yet advertised by
+        // the listing.
+        if (!isCanonicalChunkFileName(chunk.chunkFileName)) {
+          continue
+        }
+        chunkFiles.push({
+          resourceId: chunk.resourceId,
+          fileName: chunk.chunkFileName,
+          body: entry.body
+        })
+        continue
+      }
+
       if (fileName.includes('/')) {
         continue
       }
@@ -325,7 +427,8 @@ export function buildImportPlan(entries: Map<string, TarEntry>): ImportPlan {
       collectionPolicy,
       resources,
       resourcePolicies,
-      resourceMetadata
+      resourceMetadata,
+      chunkFiles
     }
   })
 

package/src/lib/paths.ts

@@ -209,6 +209,54 @@ export function metaPath({
   return `${resourcePath({ spaceId, collectionId, resourceId })}/meta`
 }
 
+/**
+ * `/space/:spaceId/:collectionId/:resourceId/chunks/:chunkIndex` -- a single
+ * chunk of a chunked Resource (the `chunked-streams` feature). Chunks are
+ * addressed under their parent Resource; like `meta`, the `chunks` segment
+ * needs no reserved-id entry (it sits a level below any Resource route).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @param options.chunkIndex {number}   non-negative integer chunk position
+ * @returns {string}
+ */
+export function chunkPath({
+  spaceId,
+  collectionId,
+  resourceId,
+  chunkIndex
+}: {
+  spaceId: string
+  collectionId: string
+  resourceId: string
+  chunkIndex: number
+}): string {
+  return `${resourcePath({ spaceId, collectionId, resourceId })}/chunks/${chunkIndex}`
+}
+
+/**
+ * `/space/:spaceId/:collectionId/:resourceId/chunks/` -- the chunk listing
+ * (container) path of a chunked Resource. Always the trailing-slash container
+ * form: a reader discovers the chunk count here before fetching `0..count-1`.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {string}
+ */
+export function chunksContainerPath({
+  spaceId,
+  collectionId,
+  resourceId
+}: {
+  spaceId: string
+  collectionId: string
+  resourceId: string
+}): string {
+  return `${resourcePath({ spaceId, collectionId, resourceId })}/chunks/`
+}
+
 /**
  * `/space/:spaceId/:collectionId/backend` -- the "Collection Backend Selected"
  * resource path (reserved `backend` segment at the Resource level).

package/src/lib/resourceFileName.ts

@@ -67,3 +67,72 @@ export function parseResourceFileName(fileName: string): {
       : 'application/octet-stream'
   }
 }
+
+/**
+ * Prefix of a Resource's per-Resource chunk directory
+ * (`.chunks.<encodedResourceId>/`), which holds the chunk representations of a
+ * chunked Resource (the `chunked-streams` feature). The leading `.` keeps the
+ * directory out of the `r.`-prefixed Collection listing, and dot-escaping the
+ * id segment keeps it in one filesystem-name namespace with the Resource files.
+ */
+export const CHUNK_DIR_PREFIX = '.chunks.'
+
+/**
+ * Builds the on-disk directory name for a Resource's chunk directory:
+ * `.chunks.<encodedResourceId>`. The id segment is dot-escaped (see
+ * {@link encodeFilenameSegment}) so a dotted id round-trips.
+ * @param resourceId {string}
+ * @returns {string}
+ */
+export function chunkDirName(resourceId: string): string {
+  return `${CHUNK_DIR_PREFIX}${encodeFilenameSegment(resourceId)}`
+}
+
+/**
+ * Largest addressable chunk index. 2^31-1 (`int4` max): the Postgres backend
+ * stores the index in an `integer` column, so the shared validation caps it
+ * there and both backends agree on the addressable range.
+ */
+export const MAX_CHUNK_INDEX = 2 ** 31 - 1
+
+/**
+ * Canonical non-negative decimal integer: `0`, or a digit run with no leading
+ * zero. Rejecting non-canonical spellings (`01`, `+1`, `1e3`) keeps every chunk
+ * addressable at exactly one URL (and at exactly one archive file name).
+ */
+const CHUNK_INDEX_PATTERN = /^(0|[1-9][0-9]*)$/
+
+/**
+ * Parses a chunk-index segment -- the `:chunkIndex` path param, or the
+ * `<index>` segment of a chunk file name (`r.<index>.<encType>.<ext>` /
+ * `.meta.<index>.json`) -- into its number. Returns `undefined` unless the
+ * segment is the canonical decimal spelling of an integer in
+ * `[0, MAX_CHUNK_INDEX]`. The single shared predicate for the live route and
+ * both backends' import paths, so a chunk index means the same thing
+ * everywhere.
+ * @param segment {string}
+ * @returns {number | undefined}
+ */
+export function parseChunkIndexSegment(segment: string): number | undefined {
+  if (!CHUNK_INDEX_PATTERN.test(segment)) {
+    return undefined
+  }
+  const chunkIndex = Number(segment)
+  return chunkIndex <= MAX_CHUNK_INDEX ? chunkIndex : undefined
+}
+
+/**
+ * Parses a chunk directory name (`.chunks.<encodedResourceId>`) back into its
+ * parent `resourceId`, reversing {@link chunkDirName}. Returns `undefined` when
+ * the name is not a chunk directory (no matching prefix, or an empty id
+ * segment).
+ * @param dirName {string}   the basename of the directory
+ * @returns {string | undefined}
+ */
+export function parseChunkDirName(dirName: string): string | undefined {
+  if (!dirName.startsWith(CHUNK_DIR_PREFIX)) {
+    return undefined
+  }
+  const encodedId = dirName.slice(CHUNK_DIR_PREFIX.length)
+  return encodedId.length > 0 ? decodeURIComponent(encodedId) : undefined
+}

package/src/plugin.ts

@@ -212,10 +212,13 @@ async function wasPlugin(
       (onboardingToken ? onboardingTokenAuthorizer(onboardingToken) : undefined)
   )
 
-  // Disable CORS
+  // Disable CORS. `exposedHeaders` is required for browser clients: without
+  // it, cross-origin JS cannot read `Location` (space/resource creation),
+  // `ETag` (metaVersion concurrency), or `Link` (pagination, policy linksets).
   fastify.register(cors, {
     origin: '*',
-    methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+    methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    exposedHeaders: ['Location', 'ETag', 'Link']
   })
 
   // Multipart file uploading. The cap is `files: 2`, not `1`: a write MUST carry