@jolly-pixel/asset-server 1.0.0

package/docs/AssetKinds.md

@@ -0,0 +1,204 @@
+# Asset kinds
+
+An `AssetKindHandler` defines how one asset type is recognized, folded into
+state and serialized.
+
+```ts
+interface AssetKindHandler<TState = unknown, TCommand = unknown> {
+  readonly kind: string;
+  readonly match: readonly string[];
+  readonly snapshot?: SnapshotPolicy;
+
+  create(assetId: string): TState;
+  apply(state: TState, event: Event): void;
+  serialize(state: TState): Promise<Uint8Array>;
+  live?(binding: AssetRoomBinding<TState>): AssetLiveProtocol<TCommand>;
+  createExtension?(binding: AssetRoomBinding<TState>): Extension;
+}
+```
+
+Handlers are checked in registration order. `match` contains globs matched
+against root-relative POSIX paths. The built-in `binary` handler receives any
+path that no registered handler claims.
+
+`apply` receives lifecycle events and domain events from the asset stream.
+`serialize` returns the bytes stored by the asset source. A handler that
+supports live editing provides `live`; other kinds have no dynamic editing
+room.
+
+`apply` must reset the existing `TState` in place for `asset.created`,
+`asset.updated` and `asset.deleted`. Each event is a complete checkpoint.
+Replay creates a fresh state, resumes at the newest checkpoint and folds later
+events. Reassigning the `state` parameter has no effect because `apply` returns
+`void` and the store retains the value returned by `create`.
+
+`TState` defaults to `unknown`, so a handler declared without it must narrow
+its own state before use. Pass the state type to keep `create`, `apply` and
+`serialize` checked against each other.
+
+## Reading lifecycle payloads
+
+`event.eventData` is typed `unknown` by the event store, because the store
+holds any domain. Parse it with `parseAssetEvent` rather than asserting a
+shape: it validates the payload against a JSON Schema for its event type and
+returns a `Result` carrying the parsed event, or the reason it was refused.
+
+```ts
+apply(state: MyState, event: Event): void {
+  const parsed = parseAssetEvent(event);
+  if (parsed.ok && parsed.val.eventType === ASSET_UPDATED) {
+    // eventData is AssetWriteData here
+    state.bytes = decodeContent(parsed.val.eventData.content);
+  }
+}
+```
+
+Payloads read straight from persistence are parsed JSON, so a corrupt row
+would otherwise reach the fold unchecked.
+
+## Snapshot policy
+
+```ts
+interface SnapshotPolicy {
+  delay?: number;
+  maxDelay?: number;
+}
+```
+
+`delay` is the quiet period after the latest domain event. `maxDelay` limits
+the time since the first unsnapshotted event. Backend defaults are `2_000` ms
+and `30_000` ms. A handler can override either value through `snapshot`.
+
+`delay: 0` schedules the snapshot for the next timer turn. Lifecycle events
+do not schedule snapshots.
+
+## Registry
+
+```ts
+const kinds = new AssetKindRegistry([pixelArtHandler]);
+
+kinds.register(voxelHandler);
+kinds.resolve("textures/grass.png");
+kinds.get("pixelart");
+```
+
+Registering the same kind twice throws. The reserved `binary` fallback cannot
+be replaced.
+
+## Built-in kinds
+
+`binary` is the reserved fallback. `texture` is a shipped handler that claims
+image files so a runtime `AssetType` of the same name can resolve them:
+
+```ts
+import { textureAssetHandler } from "@jolly-pixel/asset-server";
+
+const kinds = new AssetKindRegistry([textureAssetHandler()]);
+```
+
+Its state is the file's bytes, exactly like `binary`, and it has no `live`
+protocol, so texture assets get no editing room. The kind exists to
+name the record: `AssetCatalog.resolve()` rejects a record whose kind does not
+match its reference, and nothing on the browser side loads `binary`. Pass
+`match` to narrow the globs from the default image extensions.
+
+## Kinds shipped by other packages
+
+Two handlers live with the domain they serialize rather than here, because
+asset-server does not depend on the renderers:
+
+```ts
+import { pixelArtAssetHandler } from "@jolly-pixel/pixel-draw.renderer/asset/index.ts";
+import { voxelMapAssetHandler } from "@jolly-pixel/voxel.renderer/asset/index.ts";
+
+await createAssetBackend({
+  source,
+  eventStore,
+  handlers: [
+    pixelArtAssetHandler(),
+    voxelMapAssetHandler(),
+    textureAssetHandler()
+  ]
+});
+```
+
+Both take `@jolly-pixel/asset-server` as an optional peer dependency, so a
+browser-only consumer of either renderer never installs it.
+
+## Writing an editable kind
+
+A kind with live editing has two halves that must not overlap: `apply` is the
+only writer of state, and `live` describes a room that appends without
+writing. `AssetRoomExtension` hosts the protocol, so a kind supplies only
+what is specific to it:
+
+```ts
+interface AssetLiveProtocol<TCommand = unknown> {
+  readonly commandEventType: string;
+  readonly actions: readonly string[];
+
+  parse(payload: unknown): TCommand | null;
+  snapshot(): unknown;
+  arbitrate(
+    command: TCommand,
+    clientId: string
+  ): AssetArbitration<TCommand> | null;
+  broadcast?(command: TCommand): AssetRoomMessage;
+}
+```
+
+`live` runs once per room, so per-room state such as a conflict tracker
+belongs in the returned protocol rather than in the handler:
+
+```ts
+live(binding) {
+  const arbiter = new MyArbiter({ conflictResolver });
+  const { state } = binding;
+
+  return {
+    commandEventType: MY_COMMAND,
+    actions: MY_ACTIONS,
+    parse: (payload) => isMyCommand(payload) ? payload : null,
+    snapshot: () => state.toJSON(),
+    arbitrate(command, clientId) {
+      const admitted = arbiter.admit(command);
+      if (admitted === null) {
+        return null;
+      }
+
+      return {
+        command: admitted,
+        commit: () => arbiter.record(admitted)
+      };
+    }
+  };
+}
+```
+
+The room parses the payload, arbitrates it, appends
+`arbitration.command` under `commandEventType`, then calls
+`arbitration.commit` and broadcasts. `commit` runs only after the append
+lands, so a conflict tracker never records a command the store refused. The
+append folds through `apply` before it resolves, so state is current by the
+time peers hear about the change.
+
+`broadcast` overrides the default `{ type: "command", data: command }`
+envelope. `voxel-map` uses it to answer a `world-replace` with a full
+snapshot.
+
+`actions` names the commands the kind accepts. A configured rights table
+checks each message under `${kind}.${action}`; a payload naming no declared
+action is checked under `${kind}.invalid`.
+
+A room that also mutated the state would apply every command twice: once
+itself and once through the fold. Absolute writes survive that, but a command
+carrying a delta does not. `voxel-map`'s `offset-updated` is exactly such a
+command, which is why both shipped kinds keep the halves separate.
+
+`createExtension` remains as an escape hatch for a room protocol `live`
+cannot express, and takes precedence over it. It returns a `network.Extension`
+whose `id` must equal the room name.
+
+`apply` must never throw. Its event is already persisted, so a fold that
+aborts would break every later replay. Both shipped handlers catch, log and
+keep the last good state.

package/docs/AssetWriter.md

@@ -0,0 +1,62 @@
+# AssetWriter
+
+Use `backend.writer` to change assets. Each method appends an asset lifecycle
+event before the backend updates the catalog and source.
+
+```ts
+writer.create(input: CreateAssetInput): Promise<Result<Event, Error>>
+writer.update(input: UpdateAssetInput): Promise<Result<Event, Error>>
+writer.rename(input: RenameAssetInput): Promise<Result<Event, Error>>
+writer.remove(input: DeleteAssetInput): Promise<Result<Event, Error>>
+```
+
+Every input requires an event-store actor:
+
+```ts
+const actor = { type: "user", id: "alice" } as const;
+```
+
+## Create
+
+```ts
+const result = await backend.writer.create({
+  path: "textures/grass.png",
+  data: pngBytes,
+  actor
+});
+
+const event = result.unwrap();
+console.log(event.assetId);
+```
+
+```ts
+interface CreateAssetInput {
+  path: string;
+  data: Uint8Array;
+  actor: Actor;
+  kind?: string;
+  assetId?: string;
+}
+```
+
+The backend generates an asset ID when `assetId` is omitted. It resolves the
+kind from the registered path globs when `kind` is omitted.
+
+## Update, rename and remove
+
+```ts
+await backend.writer.update({ assetId, data: nextBytes, actor });
+await backend.writer.rename({ assetId, to: "textures/ground.png", actor });
+await backend.writer.remove({ assetId, actor });
+```
+
+These operations return an error result when the asset ID is unknown. Paths
+are
+[root-relative POSIX paths](../../asset-source/docs/AssetSource.md#paths); one
+that escapes the
+source root, or that names the `.jollypixel/` state directory, throws
+`AssetPathEscapeError`.
+
+Call `backend.flush(assetId)` when the caller must wait for the resulting
+source write. The `alreadyProjected` input option is reserved for source-backed
+reconciliation, where the bytes already exist in the source.

package/docs/Catalog.md

@@ -0,0 +1,71 @@
+# Catalog
+
+`CatalogProjection` folds asset lifecycle events into an
+`@jolly-pixel/asset` catalog.
+
+```ts
+const projection = new CatalogProjection({ eventStore });
+projection.load();
+projection.start();
+```
+
+- `load()` folds each asset's newest lifecycle checkpoint and the events
+  after it. See [Replay](./Sync.md#replay).
+- `catalog` exposes the current `AssetCatalog`.
+- `size` is the number of cataloged assets.
+- `snapshot()` returns `AssetManifestData`.
+- `changed` is emitted for each recognized lifecycle event applied to the
+  catalog. A deleted asset has `record: null`.
+- `close()` stops following appended events and removes listeners.
+
+`apply(event)` returns `false` and changes nothing for events outside the
+`asset.` prefix and for lifecycle events whose payload does not match their
+type. See [Typed payloads](./Sync.md#typed-payloads).
+
+Each catalog record uses the asset content hash as its `revision`.
+
+## Network room
+
+`CatalogExtension` provides a read-only `asset-catalog` room. A client receives
+a snapshot when it joins and catalog changes while it remains connected.
+
+```ts
+server.register(new CatalogExtension({ projection }));
+```
+
+```ts
+{ type: "catalog:snapshot", manifest: AssetManifestData }
+{ type: "catalog:changed", change: { eventType, assetId, record } }
+```
+
+`createAssetBackend().attach(server)` registers this room for the usual setup.
+
+## HTTP handler
+
+```ts
+import { createCatalogHandler } from "@jolly-pixel/asset-server/catalog";
+
+const handler = createCatalogHandler({
+  projection,
+  path: "/__jollypixel/catalog"
+});
+```
+
+The default path is `/__jollypixel/catalog`. `GET` returns the JSON snapshot
+and `HEAD` returns the same headers without a body. Other methods on that path
+receive `405` with `Allow: GET, HEAD`. Requests for another path are passed to
+`next()`.
+
+## Vite plugin
+
+```ts
+import {
+  createAssetCatalogPlugin
+} from "@jolly-pixel/asset-server/plugins/vite.ts";
+
+export default {
+  plugins: [createAssetCatalogPlugin({ projection })]
+};
+```
+
+The plugin accepts the same optional `path` override as the HTTP handler.

package/docs/Rooms.md

@@ -0,0 +1,70 @@
+# Rooms
+
+`registerAssetRooms` installs a `network` room resolver that creates one room
+for each open asset.
+
+```ts
+const clearResolver = registerAssetRooms({
+  server,
+  kinds,
+  catalog,
+  states,
+  projector,
+  scheduler,
+  graceMs: 30_000
+});
+```
+
+Most hosts call `backend.attach(server)`, which also registers the catalog
+room. The returned callback clears the resolver. It does not evict rooms that
+the server already resolved; `server.close()` disposes those rooms.
+
+## Room names
+
+```ts
+assetRoomName("pixelart", assetId); // "pixelart:<assetId>"
+parseAssetRoomName("pixelart:a:1"); // { kind: "pixelart", assetId: "a:1" }
+```
+
+The first colon separates the kind from the asset ID. Empty kinds, empty IDs
+and names without a colon are rejected.
+
+## Admission
+
+A room is created when:
+
+- the room name parses as `${kind}:${assetId}`;
+- the kind is registered and provides `live` or `createExtension`;
+- the catalog contains the asset under that kind;
+- the created extension uses the requested room name as its `id`.
+
+A kind that provides `live` is hosted by `AssetRoomExtension`, which owns
+the snapshot-on-connect, arbitrate-append-broadcast and rights-event-name
+plumbing. `createExtension` bypasses it and takes precedence.
+
+The handler receives the live state through `AssetRoomBinding`:
+
+```ts
+interface AssetRoomBinding<TState> {
+  readonly assetId: string;
+  readonly kind: string;
+  readonly roomId: string;
+  readonly state: TState;
+}
+```
+
+## Eviction
+
+The server keeps an empty dynamic room for its configured grace period. A new
+join during that period reuses the room. When the period expires, asset-server
+snapshots pending state, writes it to the source and releases the live state
+before the extension is disposed.
+
+`graceMs` overrides the server default for asset rooms. Use
+`server.settled(roomName)` to wait for asynchronous eviction. Closing the
+server evicts all resolved rooms through the same path.
+
+Rights use the extension's `name`, which asset handlers normally set to the
+asset kind. This gives every room of one kind the same rights scope.
+`AssetRoomExtension` names each event after the command's `action` when the
+protocol declares it, and `invalid` otherwise.

package/docs/Sync.md

@@ -0,0 +1,146 @@
+# Sync
+
+The event log records asset lifecycle and domain events. The backend projects
+those events to the asset source and catalog. Reconciliation converts external
+source changes into lifecycle events.
+
+## Lifecycle events
+
+The `asset.` prefix is reserved for these events:
+
+```ts
+asset.created // { path, kind, hash, size, content }
+asset.updated // { path, kind, hash, size, content }
+asset.renamed // { from, to, kind, hash }
+asset.deleted // { path, kind }
+```
+
+Create and update events store content as base64:
+
+```ts
+type AssetContent =
+  | { type: "inline"; encoding: "base64"; data: string }
+  | { type: "ref"; hash: string; size: number };
+```
+
+Only inline content is supported. `AssetInlineContent` is that branch alone,
+and it is what a parsed write payload carries, so `decodeContent()` cannot be
+handed a reference. `encodeContent()`, `decodeContent()` and the event
+constants are exported from the main package entrypoint.
+
+### Typed payloads
+
+Each payload type is derived from the JSON Schema that validates it, so the
+schema and the type cannot drift. `AssetEventDataMap` binds each event type to
+its payload, and `AssetEvent` is a stored event narrowed to a matching pair:
+
+```ts
+type AssetEventDataMap = {
+  "asset.created": AssetWriteData;
+  "asset.updated": AssetWriteData;
+  "asset.renamed": AssetRenamedData;
+  "asset.deleted": AssetDeletedData;
+};
+```
+
+`parseAssetEvent(event)` parses a stored event against that map and returns
+`Result<AssetEvent, AssetEventRejection>`. Readers use it instead of asserting
+a payload shape, because events come back from persistence as parsed JSON.
+
+A rejection says which of three things happened, and `describeRejection()`
+renders it for a log:
+
+| Reason | Meaning |
+|---|---|
+| `foreign` | another domain's event, or an `asset.` type this version does not know |
+| `malformed` | an asset event whose payload fails its schema; carries the failing paths |
+| `unsupported` | a well-formed write event carrying reference content |
+
+Payload schemas accept unknown fields, so an event written by a newer version
+of the backend stays readable rather than being skipped as malformed.
+
+A rejected event is skipped rather than folded: the projector keeps the
+asset's last good projection and warns for `malformed` and `unsupported`, and
+the catalog keeps its last good record and returns `false` from `apply`.
+Neither aborts a replay, so one corrupt row cannot stop the backend from
+starting.
+
+## Snapshots
+
+Domain events update the live state held by an asset kind handler. The
+`SnapshotScheduler` serializes that state and appends `asset.updated` after the
+configured quiet period, capped by the maximum delay. A snapshot is skipped
+when the serialized bytes have the current content hash.
+
+`backend.flush(assetId?)`, room eviction and backend shutdown flush pending
+snapshots. See [Asset kinds](./AssetKinds.md#snapshot-policy) for cadence.
+
+## Replay
+
+```ts
+states.acquire(assetId: string, kind: string): Promise<AssetStateEntry>
+```
+
+Snapshots double as replay checkpoints. `acquire` folds only from the newest
+`asset.created`, `asset.updated` or `asset.deleted`, so replay cost tracks
+edits since the last snapshot rather than the whole history. The fold yields
+periodically, so a long stream cannot hold the event loop while other rooms
+resolve, and concurrent callers share one replay. It re-reads the tail until
+the stream stops growing, because events appended while it yielded land before
+the entry starts following the log.
+
+Those three types are exported as `ASSET_CHECKPOINT_EVENT_TYPES`. Loading a
+projection uses the same bound: `AssetProjector.load()` and
+`CatalogProjection.load()` read from each asset's newest checkpoint rather
+than the head of the log, because an older `asset.created` or `asset.updated`
+only produces a projection the replay overwrites. `asset.renamed` is not a
+checkpoint: it folds onto the projection before it, and is read as part of the
+tail. Startup cost therefore tracks the number of assets, not the depth of the
+log. See [Workspace compaction](./Workspace.md#compaction) for removing what
+this skips.
+
+## Reconciliation
+
+```ts
+reconciler.reconcile(): Promise<Result<ReconcileReport, Error>>
+
+interface ReconcileReport {
+  readonly created: number;
+  readonly updated: number;
+  readonly renamed: number;
+  readonly deleted: number;
+  readonly failed: number;
+}
+```
+
+A successful result counts lifecycle events appended during the scan. An
+unreadable entry increments `failed` without stopping other entries. Failure to
+list the source returns an error result for the whole scan.
+
+Renames are recognized when one removed path and one added path have the same
+unique content hash. Ambiguous matches are recorded as deletion and creation.
+Byte-identical changes append no event.
+
+On a source with `watch()`, `ReconciliationWatcher` groups notifications using
+the configured debounce. Its public controls are:
+
+```ts
+watcher.start(): void
+watcher.notify(path: string): void
+watcher.run(): Promise<void>
+watcher.settle(): Promise<void>
+watcher.close(): Promise<void>
+```
+
+`run()` starts a scan immediately. `settle()` only waits for a scan already in
+progress.
+
+## Projection state
+
+`.jollypixel/state.json` stores the last projected event ID for each asset. It
+is machine-local and can be recreated by replaying the event log. Projection
+failures are retained there for inspection and retried by a later flush.
+
+`.jollypixel/assets.json` has a different purpose. It maps paths to asset IDs
+for discovery when a checkout has no local event log. Commit this file when
+asset IDs must remain stable across checkouts.