ignotum 0.0.7 → 0.0.8

package/src/dev-runtime/files.ts

@@ -0,0 +1,338 @@
+import { encodeCanonicalJson } from "@ignotum/contracts/json";
+import { validateApplicationFile } from "@ignotum/contracts/schema/file-content";
+import {
+  FileGrantToken,
+  FileId,
+  FileUploadToken,
+  RuntimeFileOccurrence,
+  encodedFileOccurrencesOf,
+  fileLimits,
+  type RuntimeFileMetadata,
+  type RuntimeFileOccurrence as RuntimeFileOccurrenceValue,
+} from "@ignotum/contracts/schema/file";
+import type { FunctionAddress, SubscriptionId } from "@ignotum/contracts/runtime/sync";
+import { fileGrantUrlPrefix, fileUploadUrlPrefix } from "@ignotum/contracts/runtime/transport";
+import type { InvocationId } from "@ignotum/contracts/runtime/identity";
+import { IdGenerator } from "@ignotum/shared/id";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+
+interface Preparation {
+  readonly function: FunctionAddress;
+  readonly args: Schema.Json;
+  readonly files: ReadonlyArray<RuntimeFileOccurrenceValue>;
+  readonly uploads: ReadonlyMap<FileId, FileUploadToken>;
+}
+
+interface Grant {
+  readonly subscriptionId: SubscriptionId;
+  readonly file: RuntimeFileMetadata;
+}
+
+const StoredFile = Schema.Struct({
+  fileId: FileId,
+  name: Schema.String,
+  format: RuntimeFileOccurrence.fields.file.fields.format,
+  size: Schema.Natural,
+  ready: Schema.Literals([0, 1]),
+});
+
+const StoredDocumentFields = Schema.Struct({ fields: Schema.String });
+const JsonObjectString = Schema.fromJsonString(Schema.JsonObject);
+
+interface LocalApplicationFilesService {
+  readonly prepare: (
+    invocationId: InvocationId,
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+    files: ReadonlyArray<RuntimeFileOccurrenceValue>,
+  ) => Effect.Effect<ReadonlyArray<RuntimeFileOccurrenceValue & { readonly url?: string }>>;
+  readonly admit: (
+    invocationId: InvocationId,
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+  ) => Effect.Effect<ReadonlyArray<RuntimeFileOccurrenceValue>>;
+  readonly upload: (token: FileUploadToken, bytes: Uint8Array) => Effect.Effect<string>;
+  readonly grants: (
+    subscriptionId: SubscriptionId,
+    files: ReadonlyArray<RuntimeFileOccurrenceValue>,
+  ) => Effect.Effect<ReadonlyArray<RuntimeFileOccurrenceValue & { readonly url: string }>>;
+  readonly releaseGrants: (subscriptionId: SubscriptionId) => Effect.Effect<void>;
+  readonly readGrant: (
+    token: FileGrantToken,
+  ) => Effect.Effect<
+    Option.Option<{ readonly file: RuntimeFileMetadata; readonly bytes: Uint8Array }>
+  >;
+  readonly reconcile: Effect.Effect<void>;
+  readonly releasePreparation: (invocationId: InvocationId) => Effect.Effect<void>;
+}
+
+export const LocalApplicationFiles = Context.Reference<LocalApplicationFilesService>(
+  "ignotum/dev-runtime/files/LocalApplicationFiles",
+  {
+    defaultValue: () => ({
+      admit: (_invocationId, _functionAddress, args) =>
+        Effect.succeed(encodedFileOccurrencesOf(args)),
+      grants: (_subscriptionId, files) =>
+        Effect.succeed(files.map((file) => ({ ...file, url: "" }))),
+      prepare: (_invocationId, _functionAddress, _args, files) => Effect.succeed(files),
+      upload: () => Effect.die("Local application file storage is unavailable."),
+      releaseGrants: () => Effect.void,
+      readGrant: () => Effect.succeed(Option.none()),
+      reconcile: Effect.void,
+      releasePreparation: () => Effect.void,
+    }),
+  },
+);
+
+const sameFile = (left: RuntimeFileMetadata, right: RuntimeFileMetadata): boolean =>
+  left.id === right.id &&
+  left.format === right.format &&
+  left.name === right.name &&
+  left.size === right.size;
+
+const validFilename = (name: string): boolean => {
+  const bytes = new TextEncoder().encode(name).byteLength;
+  const hasControlCharacter = Array.from(name).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 0x1f || codePoint === 0x7f;
+  });
+  return (
+    bytes > 0 &&
+    bytes <= fileLimits.filenameBytes &&
+    !hasControlCharacter &&
+    !name.includes("/") &&
+    !name.includes("\\")
+  );
+};
+
+export const localApplicationFilesLayer = (appDirectory: string) =>
+  Layer.effect(
+    LocalApplicationFiles,
+    Effect.gen(function* () {
+      const ids = yield* IdGenerator;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const sql = yield* SqlClient.SqlClient;
+      const directory = path.join(appDirectory, ".ignotum", "files");
+      yield* fileSystem.makeDirectory(directory, { recursive: true }).pipe(Effect.orDie);
+      const preparations = new Map<InvocationId, Preparation>();
+      const uploadFiles = new Map<FileUploadToken, RuntimeFileMetadata>();
+      const grants = new Map<FileGrantToken, Grant>();
+      const objectPath = (fileId: FileId) => path.join(directory, fileId);
+
+      const prepare = Effect.fn("LocalApplicationFiles.prepare")(function* (
+        invocationId: InvocationId,
+        functionAddress: FunctionAddress,
+        args: Schema.Json,
+        files: ReadonlyArray<RuntimeFileOccurrenceValue>,
+      ) {
+        const existing = preparations.get(invocationId);
+        if (existing !== undefined) {
+          if (
+            existing.function !== functionAddress ||
+            encodeCanonicalJson(existing.args) !== encodeCanonicalJson(args) ||
+            encodeCanonicalJson(existing.files) !== encodeCanonicalJson(files)
+          ) {
+            throw new Error("The invocation ID already belongs to another file preparation.");
+          }
+          return files.map((occurrence) => {
+            const token = existing.uploads.get(occurrence.file.id);
+            return token === undefined
+              ? occurrence
+              : { ...occurrence, url: `${fileUploadUrlPrefix}${token}` };
+          });
+        }
+        const all = new Map(
+          encodedFileOccurrencesOf(args).map((occurrence) => [
+            encodeCanonicalJson(occurrence.path),
+            occurrence.file,
+          ]),
+        );
+        const distinct = new Map<FileId, RuntimeFileMetadata>();
+        for (const occurrence of files) {
+          const arg = all.get(encodeCanonicalJson(occurrence.path));
+          if (
+            arg === undefined ||
+            !sameFile(arg, occurrence.file) ||
+            !validFilename(occurrence.file.name)
+          ) {
+            throw new Error("Prepared files do not match the mutation arguments.");
+          }
+          const prior = distinct.get(occurrence.file.id);
+          if (prior !== undefined && !sameFile(prior, occurrence.file)) {
+            throw new Error("One file ID has conflicting metadata.");
+          }
+          distinct.set(occurrence.file.id, occurrence.file);
+        }
+        if (distinct.size > fileLimits.filesPerMutation) throw new Error("Too many files.");
+        const totalBytes = [...distinct.values()].reduce((total, file) => total + file.size, 0);
+        if (totalBytes > fileLimits.mutationBytes) throw new Error("File uploads are too large.");
+
+        const staged = yield* sql<{ readonly bytes: number }>`
+          SELECT COALESCE(SUM(size), 0) AS bytes FROM applicationFiles WHERE ready = 0
+        `;
+        let additionalStagedBytes = 0;
+        for (const file of distinct.values()) {
+          const rows = yield* sql<typeof StoredFile.Type>`
+            SELECT fileId, name, format, size, ready FROM applicationFiles WHERE fileId = ${file.id}
+          `;
+          const stored = rows[0];
+          if (stored === undefined) additionalStagedBytes += file.size;
+          else if (
+            !sameFile(
+              {
+                id: stored.fileId,
+                name: stored.name,
+                format: stored.format,
+                size: stored.size,
+              },
+              file,
+            )
+          ) {
+            throw new Error(`File '${file.id}' has conflicting metadata.`);
+          }
+        }
+        if ((staged[0]?.bytes ?? 0) + additionalStagedBytes > fileLimits.stagedBytesPerApp) {
+          throw new Error("The app has too many staged file bytes.");
+        }
+        const uploads = new Map<FileId, FileUploadToken>();
+        for (const file of distinct.values()) {
+          const rows = yield* sql<typeof StoredFile.Type>`
+            SELECT fileId, name, format, size, ready FROM applicationFiles WHERE fileId = ${file.id}
+          `;
+          const stored = rows[0];
+          if (stored !== undefined && stored.ready === 1) continue;
+          const token = yield* ids.generate(FileUploadToken);
+          uploads.set(file.id, token);
+          uploadFiles.set(token, file);
+          yield* sql`
+            INSERT INTO applicationFiles (fileId, name, format, size, ready)
+            VALUES (${file.id}, ${file.name}, ${file.format}, ${file.size}, 0)
+            ON CONFLICT(fileId) DO UPDATE SET
+              name = excluded.name, format = excluded.format, size = excluded.size
+          `;
+        }
+        preparations.set(invocationId, { function: functionAddress, args, files, uploads });
+        return files.map((occurrence) => {
+          const token = uploads.get(occurrence.file.id);
+          return token === undefined
+            ? occurrence
+            : { ...occurrence, url: `${fileUploadUrlPrefix}${token}` };
+        });
+      });
+
+      const admit = Effect.fn("LocalApplicationFiles.admit")(function* (
+        invocationId: InvocationId,
+        functionAddress: FunctionAddress,
+        args: Schema.Json,
+      ) {
+        const preparation = preparations.get(invocationId);
+        if (
+          preparation !== undefined &&
+          (preparation.function !== functionAddress ||
+            encodeCanonicalJson(preparation.args) !== encodeCanonicalJson(args))
+        ) {
+          throw new Error("The mutation does not match its file preparation.");
+        }
+        for (const occurrence of preparation?.files ?? []) {
+          const rows = yield* sql<{ readonly ready: number }>`
+            SELECT ready FROM applicationFiles WHERE fileId = ${occurrence.file.id}
+          `;
+          if (rows[0]?.ready !== 1) throw new Error("A prepared file has not finished uploading.");
+        }
+        const occurrences = encodedFileOccurrencesOf(args);
+        for (const occurrence of occurrences) {
+          const rows = yield* sql<{ readonly ready: number }>`
+            SELECT ready FROM applicationFiles WHERE fileId = ${occurrence.file.id}
+          `;
+          if (rows[0]?.ready !== 1) throw new Error(`File '${occurrence.file.id}' is unavailable.`);
+        }
+        return occurrences;
+      });
+
+      const upload = Effect.fn("LocalApplicationFiles.upload")(function* (
+        token: FileUploadToken,
+        bytes: Uint8Array,
+      ) {
+        const file = uploadFiles.get(token);
+        if (file === undefined) throw new Error("The local file upload ticket is invalid.");
+        const validation = validateApplicationFile(bytes, file.format, file.size);
+        if (!validation.valid) throw new Error(validation.message);
+        yield* fileSystem.writeFile(objectPath(file.id), bytes).pipe(Effect.orDie);
+        yield* sql`UPDATE applicationFiles SET ready = 1 WHERE fileId = ${file.id}`;
+        uploadFiles.delete(token);
+        return "Stored";
+      });
+
+      const grantFiles = Effect.fn("LocalApplicationFiles.grants")(function* (
+        subscriptionId: SubscriptionId,
+        occurrences: ReadonlyArray<RuntimeFileOccurrenceValue>,
+      ) {
+        for (const [token, grant] of grants) {
+          if (grant.subscriptionId === subscriptionId) grants.delete(token);
+        }
+        const tokens = new Map<FileId, FileGrantToken>();
+        for (const occurrence of occurrences) {
+          if (tokens.has(occurrence.file.id)) continue;
+          const token = yield* ids.generate(FileGrantToken);
+          tokens.set(occurrence.file.id, token);
+          grants.set(token, { subscriptionId, file: occurrence.file });
+        }
+        return occurrences.map((occurrence) => ({
+          ...occurrence,
+          url: `${fileGrantUrlPrefix}${tokens.get(occurrence.file.id)}`,
+        }));
+      });
+
+      const reconcile = Effect.gen(function* () {
+        const rows = yield* sql<typeof StoredDocumentFields.Type>`
+          SELECT fields FROM documents
+        `;
+        const referenced = new Set<FileId>();
+        for (const row of rows) {
+          const fields = yield* Schema.decodeEffect(JsonObjectString)(row.fields).pipe(
+            Effect.orDie,
+          );
+          for (const occurrence of encodedFileOccurrencesOf(fields))
+            referenced.add(occurrence.file.id);
+        }
+        const stored = yield* sql<typeof StoredFile.Type>`
+          SELECT fileId, name, format, size, ready FROM applicationFiles
+        `;
+        for (const file of stored) {
+          if (referenced.has(file.fileId)) continue;
+          yield* fileSystem.remove(objectPath(file.fileId), { force: true }).pipe(Effect.orDie);
+          yield* sql`DELETE FROM applicationFiles WHERE fileId = ${file.fileId}`;
+        }
+      });
+
+      return LocalApplicationFiles.of({
+        admit: (...args) => admit(...args).pipe(Effect.orDie),
+        grants: grantFiles,
+        readGrant: (token) => {
+          const grant = grants.get(token);
+          return grant === undefined
+            ? Effect.succeed(Option.none())
+            : fileSystem.readFile(objectPath(grant.file.id)).pipe(
+                Effect.orDie,
+                Effect.map((bytes) => Option.some({ file: grant.file, bytes })),
+              );
+        },
+        reconcile: reconcile.pipe(Effect.orDie),
+        releaseGrants: (subscriptionId) =>
+          Effect.sync(() => {
+            for (const [token, grant] of grants) {
+              if (grant.subscriptionId === subscriptionId) grants.delete(token);
+            }
+          }),
+        releasePreparation: (invocationId) =>
+          Effect.suspend(() => {
+            if (!preparations.delete(invocationId)) return Effect.void;
+            return reconcile.pipe(Effect.orDie);
+          }),
+        prepare: (...args) => prepare(...args).pipe(Effect.orDie),
+        upload: (...args) => upload(...args).pipe(Effect.orDie),
+      });
+    }),
+  );

package/src/dev-runtime/functions.ts

@@ -10,6 +10,7 @@ import { type RuntimeSchemaDefinition } from "@ignotum/contracts/runtime/schema"
 import { ErrorValueSchema, type ErrorValue } from "@ignotum/contracts/runtime/result";
 import { RequestId } from "@ignotum/contracts/runtime/id";
 import { IdGenerator } from "@ignotum/shared/id";
+import { encodedFileOccurrencesOf } from "@ignotum/contracts/schema/file";
 import type { RuntimeInvocationResult } from "@ignotum/contracts/runtime/hosted";
 import {
   FunctionAddress,
@@ -176,12 +177,19 @@ export class FunctionExecutor extends Context.Service<
             kind === "Query"
               ? database.trackedQueryTransaction(resolved.schema, invoke).pipe(
                   Effect.map(
-                    ({ dependencies, observedRevision, value }): RuntimeInvocationResult => ({
-                      type: "Query",
-                      result: value,
-                      dependencies,
-                      observedRevision,
-                    }),
+                    ({ dependencies, observedRevision, value }): RuntimeInvocationResult => {
+                      const files =
+                        value.type === "Success" && value.value !== undefined
+                          ? encodedFileOccurrencesOf(value.value)
+                          : [];
+                      const result = {
+                        type: "Query",
+                        result: value,
+                        dependencies,
+                        observedRevision,
+                      } as const;
+                      return files.length === 0 ? result : { ...result, files };
+                    },
                   ),
                 )
               : mutationSemaphore.withPermits(1)(

package/src/dev-runtime/migrations.ts

@@ -75,9 +75,23 @@ const addDevelopmentIndexes = Effect.gen(function* () {
   `;
 });
 
+const addApplicationFiles = Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  yield* sql`
+    CREATE TABLE applicationFiles (
+      fileId TEXT PRIMARY KEY NOT NULL,
+      name TEXT NOT NULL,
+      format TEXT NOT NULL CHECK (format IN ('jpeg', 'png', 'webp', 'avif', 'gif')),
+      size INTEGER NOT NULL CHECK (size >= 0),
+      ready INTEGER NOT NULL DEFAULT 0 CHECK (ready IN (0, 1))
+    ) STRICT
+  `;
+});
+
 export const developmentMigrationLoader = Migrator.fromRecord({
   "0001_initial_development_schema": initialDevelopmentSchema,
   "0002_application_indexes": addDevelopmentIndexes,
+  "0003_application_files": addApplicationFiles,
 });
 
 interface DevelopmentDatabaseService {

package/src/dev-runtime/sync.ts

@@ -44,6 +44,15 @@ import { SqlClient, SqlError, SqlSchema } from "effect/unstable/sql";
 import type * as Socket from "effect/unstable/socket/Socket";
 import type { Plugin, ViteDevServer } from "vite";
 import { FunctionRuntime, type PreparedFunction } from "@ignotum/runtime/functions";
+import {
+  FileGrantToken,
+  FileUploadToken,
+  encodedFileOccurrencesOf,
+  fileLimits,
+  fileMimeTypes,
+} from "@ignotum/contracts/schema/file";
+import { fileGrantUrlPrefix, fileUploadUrlPrefix } from "@ignotum/contracts/runtime/transport";
+import { collectStreamBytes } from "@ignotum/shared/http-body";
 import {
   makeDependencyIndex,
   QueryInvalidation,
@@ -56,6 +65,7 @@ import { LocalDatabase } from "./database.js";
 import { idGeneratorLayer } from "./id.js";
 import { DevelopmentDatabase } from "./migrations.js";
 import { FunctionExecutor, FunctionRegistry, functionRuntimeLayer } from "./functions.js";
+import { LocalApplicationFiles, localApplicationFilesLayer } from "./files.js";
 
 interface QuerySubscription {
   readonly args: Schema.Json;
@@ -186,6 +196,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
   const runtime = yield* FunctionRuntime;
   const invalidation = yield* QueryInvalidation;
   const mutationReplay = yield* MutationReplay;
+  const files = yield* LocalApplicationFiles;
   const subscriptions = yield* Ref.make(HashMap.empty<SubscriptionId, QuerySubscription>());
   const dependencyIndex = makeDependencyIndex<SubscriptionId>();
   const invocationFibers = yield* FiberSet.make();
@@ -268,12 +279,14 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
       }
       dependencyIndex.record(subscriptionId, result.dependencies);
       if ((yield* invalidation.latestRevision) > result.observedRevision) continue;
-      yield* deliver({
+      const granted = yield* files.grants(subscriptionId, result.files ?? []);
+      const snapshot = {
         type: "Snapshot",
         id: subscriptionId,
         result: result.result,
         revision: result.observedRevision,
-      });
+      } as const;
+      yield* deliver(granted.length === 0 ? snapshot : { ...snapshot, files: granted });
       return;
     }
   });
@@ -325,6 +338,12 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
     message: Extract<ClientMessage, { readonly type: "Subscribe" }>,
   ) {
     const operation = operationForSubscription(message.id);
+    if (encodedFileOccurrencesOf(message.args).length > 0) {
+      yield* send(
+        protocolError("InvalidArguments", "Queries cannot take files as arguments.", operation),
+      );
+      return;
+    }
     const current = yield* Ref.get(subscriptions);
 
     if (HashMap.has(current, message.id)) {
@@ -365,6 +384,22 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
     message: Extract<ClientMessage, { readonly type: "Invoke" }>,
   ) {
     const operation: Operation = { type: "Invocation", id: message.id };
+    const admitted = yield* files.admit(message.id, message.function, message.args).pipe(
+      Effect.as(true),
+      Effect.catchCause((cause) =>
+        send(
+          protocolError(
+            "InvalidArguments",
+            `The mutation files could not be admitted: ${String(cause)}`,
+            operation,
+          ),
+        ).pipe(Effect.as(false)),
+      ),
+    );
+    if (!admitted) {
+      yield* files.releasePreparation(message.id);
+      return;
+    }
     const prepared = yield* runtime.prepare(message.function, "Mutation", message.args).pipe(
       Effect.catchTags({
         FunctionUnavailable: (error) => sendResolutionError(operation, error),
@@ -375,6 +410,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
     );
 
     if (prepared === undefined) {
+      yield* files.releasePreparation(message.id);
       return;
     }
 
@@ -425,6 +461,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
               ),
             ),
         }),
+        Effect.ensuring(files.releasePreparation(message.id)),
         Effect.catchCause((cause) =>
           Effect.logError("A mutation invocation fiber failed.").pipe(
             Effect.annotateLogs({ cause, function: message.function, requestId: message.id }),
@@ -435,6 +472,24 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
       );
   });
 
+  const handlePrepareMutation = Effect.fn("SyncServer.handlePrepareMutation")(function* (
+    message: Extract<ClientMessage, { readonly type: "PrepareMutation" }>,
+  ) {
+    const operation: Operation = { type: "Invocation", id: message.id };
+    yield* files.prepare(message.id, message.function, message.args, message.files).pipe(
+      Effect.flatMap((uploads) => send({ type: "MutationPrepared", id: message.id, uploads })),
+      Effect.catchCause((cause) =>
+        send(
+          protocolError(
+            "InvalidArguments",
+            `The mutation files could not be prepared: ${String(cause)}`,
+            operation,
+          ),
+        ),
+      ),
+    );
+  });
+
   const handleMessage = Effect.fn("SyncServer.handleMessage")(function* (text: string) {
     const message = yield* Schema.decodeEffect(ClientMessageJson)(text).pipe(
       Effect.catch(() =>
@@ -453,6 +508,10 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
       case "Unsubscribe":
         dependencyIndex.remove(message.id);
         yield* Ref.update(subscriptions, HashMap.remove(message.id));
+        yield* files.releaseGrants(message.id);
+        return;
+      case "PrepareMutation":
+        yield* handlePrepareMutation(message);
         return;
       case "Invoke":
         yield* handleInvoke(message);
@@ -460,9 +519,22 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (socket:
     }
   });
 
-  yield* socket.runString((text) => messageSemaphore.withPermits(1)(handleMessage(text)), {
-    onOpen: send({ type: "Handshake", ...localSyncIdentity }).pipe(Effect.orDie),
-  });
+  yield* socket
+    .runString((text) => messageSemaphore.withPermits(1)(handleMessage(text)), {
+      onOpen: send({ type: "Handshake", ...localSyncIdentity }).pipe(Effect.orDie),
+    })
+    .pipe(
+      Effect.ensuring(
+        Ref.get(subscriptions).pipe(
+          Effect.flatMap((active) =>
+            Effect.forEach(HashMap.keys(active), (subscriptionId) =>
+              files.releaseGrants(subscriptionId),
+            ),
+          ),
+          Effect.asVoid,
+        ),
+      ),
+    );
 });
 
 interface SyncHandlersService {
@@ -500,6 +572,10 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
     queryInvalidationLayer,
     persistenceLayer,
     NodeServices.layer,
+    localApplicationFilesLayer(appDirectory).pipe(
+      Layer.provideMerge(DevelopmentDatabase.layer),
+      Layer.provide(Layer.mergeAll(idGeneratorLayer, sqliteLayer, NodeServices.layer)),
+    ),
   );
 
   return Layer.effect(
@@ -522,6 +598,48 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
       const httpApp = Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest;
         const pathname = new URL(request.url, "http://ignotum.local").pathname;
+        if (pathname.startsWith(fileUploadUrlPrefix)) {
+          if (request.method !== "PUT")
+            return HttpServerResponse.text("Method Not Allowed", { status: 405 });
+          const token = Schema.decodeOption(FileUploadToken)(
+            pathname.slice(fileUploadUrlPrefix.length),
+          );
+          if (Option.isNone(token)) return HttpServerResponse.text("Not Found", { status: 404 });
+          const bytes = yield* collectStreamBytes(
+            request.stream,
+            fileLimits.fileBytes,
+            () => new Error("The local application file is too large."),
+          ).pipe(Effect.orDie);
+          return yield* LocalApplicationFiles.pipe(
+            Effect.flatMap((storage) => storage.upload(token.value, bytes)),
+            Effect.match({
+              onFailure: (error) => HttpServerResponse.text(String(error), { status: 422 }),
+              onSuccess: () => HttpServerResponse.text("Stored", { status: 201 }),
+            }),
+          );
+        }
+        if (pathname.startsWith(fileGrantUrlPrefix)) {
+          if (request.method !== "GET" && request.method !== "HEAD") {
+            return HttpServerResponse.text("Method Not Allowed", { status: 405 });
+          }
+          const token = Schema.decodeOption(FileGrantToken)(
+            pathname.slice(fileGrantUrlPrefix.length),
+          );
+          if (Option.isNone(token)) return HttpServerResponse.text("Not Found", { status: 404 });
+          const granted = yield* LocalApplicationFiles.pipe(
+            Effect.flatMap((storage) => storage.readGrant(token.value)),
+          );
+          if (Option.isNone(granted)) return HttpServerResponse.text("Not Found", { status: 404 });
+          const headers = {
+            "cache-control": "private, no-store",
+            "content-length": String(granted.value.bytes.byteLength),
+            "content-type": fileMimeTypes[granted.value.file.format],
+            "x-content-type-options": "nosniff",
+          };
+          return request.method === "HEAD"
+            ? HttpServerResponse.empty({ headers })
+            : HttpServerResponse.uint8Array(granted.value.bytes, { headers });
+        }
         return yield* HttpServerResponse.json(
           pathname === syncPath
             ? { code: "UpgradeRequired", message: `Connect to ${syncPath} with WebSocket.` }

package/src/internal/api.ts

@@ -3,12 +3,23 @@ import type { Effect } from "effect";
 
 import type { ErrorValue, InternalServerError } from "@ignotum/contracts/runtime/result";
 import { FunctionAddress } from "@ignotum/contracts/runtime/sync";
+import type { FileValue } from "@ignotum/contracts/schema/file";
 
 const FunctionReferenceTypeId: unique symbol = Symbol.for("ignotum/internal/api/FunctionReference");
 declare const FunctionReferenceTypesTypeId: unique symbol;
 
 type FunctionKind = "Mutation" | "Query";
 
+export type MutationInput<Value> = Value extends FileValue
+  ? Value | File
+  : Value extends Date
+    ? Value
+    : Value extends ReadonlyArray<infer Item>
+      ? ReadonlyArray<MutationInput<Item>>
+      : Value extends object
+        ? { readonly [Key in keyof Value]: MutationInput<Value[Key]> }
+        : Value;
+
 export interface FunctionReference<
   Kind extends FunctionKind,
   Args,
@@ -58,7 +69,11 @@ type ReferenceOf<Definition> = Definition extends {
   ? HandlerArguments extends readonly [infer _Context, ...infer Rest]
     ? FunctionReference<
         Kind,
-        Rest extends readonly [infer Args, ...ReadonlyArray<unknown>] ? Args : void,
+        Rest extends readonly [infer Args, ...ReadonlyArray<unknown>]
+          ? Kind extends "Mutation"
+            ? MutationInput<Args>
+            : Args
+          : void,
         Success,
         | (Yielded extends Effect.Effect<unknown, infer Failure extends ErrorValue, never>
             ? Failure

package/src/server/index.ts

@@ -5,4 +5,11 @@ import { defineSchema as defineContractSchema } from "@ignotum/contracts/schema"
 export const Result: typeof contractResult = contractResult;
 export type Result<Success, Failure extends ErrorValue> = ContractResult<Success, Failure>;
 export const defineSchema: typeof defineContractSchema = defineContractSchema;
-export type { DefinedSchema, SchemaAuthoring } from "@ignotum/contracts/schema";
+export type {
+  DefinedSchema,
+  FileFormat,
+  FileMetadata,
+  FileMimeType,
+  FileValue,
+  SchemaAuthoring,
+} from "@ignotum/contracts/schema";