ignotum 0.0.7 → 0.0.9

package/src/client/files.ts

@@ -0,0 +1,153 @@
+import {
+  FileId,
+  fileGrantUrlOf,
+  fileIdOf,
+  fileFormats,
+  fileLimits,
+  fileMimeTypes,
+  grantFileValue,
+  isFileValue,
+  makeFileValue,
+  type FileFormat,
+  type FileValue,
+} from "@ignotum/contracts/schema/file";
+import { IdGenerator } from "@ignotum/shared/id";
+import { Effect, Predicate } from "effect";
+
+export const Files = {
+  url: (file: FileValue): string => {
+    const url = fileGrantUrlOf(file);
+    if (url === undefined) {
+      throw new Error("This FileValue has no active query grant.");
+    }
+    return url;
+  },
+} as const;
+
+const formatByMime: Partial<Record<string, FileFormat>> = {};
+for (const format of fileFormats) formatByMime[fileMimeTypes[format]] = format;
+
+const collectNativeFiles = (
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- This is the recursive parser for generated mutation arguments and native File values.
+  value: unknown,
+  files: Array<File>,
+): void => {
+  if (value instanceof File) {
+    files.push(value);
+    return;
+  }
+  if (isFileValue(value) || Predicate.isDate(value)) return;
+  if (globalThis.Array.isArray(value)) {
+    for (const child of value) collectNativeFiles(child, files);
+    return;
+  }
+  if (!Predicate.isObject(value)) return;
+  for (const child of Object.values(value)) collectNativeFiles(child, files);
+};
+
+const replaceNativeFiles = (
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Each node is classified before it is copied into the transport value.
+  value: unknown,
+  replacements: ReadonlyMap<File, FileValue>,
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- The generated function schema validates the reconstructed argument value on the server.
+): unknown => {
+  if (value instanceof File) return replacements.get(value);
+  if (isFileValue(value) || Predicate.isDate(value)) return value;
+  if (globalThis.Array.isArray(value))
+    return value.map((child) => replaceNativeFiles(child, replacements));
+  if (!Predicate.isObject(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, replaceNativeFiles(child, replacements)]),
+  );
+};
+
+export interface PreparedMutationArguments {
+  readonly value: unknown;
+  readonly nativeFiles: ReadonlyMap<FileId, File>;
+  readonly fileIds: ReadonlyArray<FileId>;
+}
+
+export const prepareMutationArguments = Effect.fn("SyncClient.prepareMutationArguments")(function* (
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Generated mutation argument types are erased only at this transport preparation boundary.
+  input: unknown,
+) {
+  const ids = yield* IdGenerator;
+  const native: File[] = [];
+  collectNativeFiles(input, native);
+  const unique = new Set(native);
+  if (unique.size > fileLimits.filesPerMutation) {
+    throw new Error(`A mutation may upload at most ${fileLimits.filesPerMutation} files.`);
+  }
+  const totalBytes = [...unique].reduce((total, file) => total + file.size, 0);
+  if (totalBytes > fileLimits.mutationBytes) {
+    throw new Error(`Mutation uploads may total at most ${fileLimits.mutationBytes} bytes.`);
+  }
+  const replacements = new Map<File, FileValue>();
+  const nativeFiles = new Map<FileId, File>();
+  for (const file of unique) {
+    const format = formatByMime[file.type.toLowerCase()];
+    if (format === undefined) {
+      throw new Error(
+        `File '${file.name}' has unsupported media type '${file.type || "unknown"}'.`,
+      );
+    }
+    if (file.size === 0 || file.size > fileLimits.fileBytes) {
+      throw new Error(`File '${file.name}' must be between 1 and ${fileLimits.fileBytes} bytes.`);
+    }
+    if (new TextEncoder().encode(file.name).byteLength > fileLimits.filenameBytes) {
+      throw new Error(`File '${file.name}' has a filename that is too long.`);
+    }
+    const id = yield* ids.generate(FileId);
+    replacements.set(file, makeFileValue(id, { format, name: file.name, size: file.size }));
+    nativeFiles.set(id, file);
+  }
+  const value = replaceNativeFiles(input, replacements);
+  return {
+    value,
+    nativeFiles,
+    fileIds: Array.from(nativeFiles.keys()),
+  } satisfies PreparedMutationArguments;
+});
+
+interface FileGrant {
+  readonly id: FileId;
+  readonly url: string;
+}
+
+// @effect-diagnostics-next-line missingPipeableSignature:off File grant attachment naturally takes the decoded value first.
+export const applyFileGrants = (
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Query result types are erased at the wire decoding boundary and checked against grant identities below.
+  value: unknown,
+  grants: ReadonlyArray<FileGrant>,
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- The traversal preserves the decoded query result shape while attaching private symbols.
+): unknown => {
+  const byId = new Map<FileId, string>();
+  for (const grant of grants) {
+    if (byId.has(grant.id)) throw new Error("A query file grant ID is duplicated.");
+    byId.set(grant.id, grant.url);
+  }
+  const matched = new Set<FileId>();
+  const visit = (
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- This recursive visitor identifies file values before attaching grants.
+    current: unknown,
+    // oxlint-disable-next-line anti-slop/no-unknown-returns -- Recursive branches preserve their input shape.
+  ): unknown => {
+    if (isFileValue(current)) {
+      const id = fileIdOf(current);
+      const url = byId.get(id);
+      if (url === undefined) return current;
+      matched.add(id);
+      return grantFileValue(current, url);
+    }
+    if (globalThis.Array.isArray(current)) {
+      return current.map(visit);
+    }
+    if (!Predicate.isObject(current) || Predicate.isDate(current)) {
+      return current;
+    }
+    return Object.fromEntries(Object.entries(current).map(([key, child]) => [key, visit(child)]));
+  };
+  const granted = visit(value);
+  if (matched.size !== byId.size) throw new Error("A query file grant has no result value.");
+  return granted;
+};

package/src/client/hooks.ts

@@ -10,11 +10,7 @@ import {
   type PaginationPage,
 } from "@ignotum/contracts/runtime/pagination";
 import { encodeTransportObject } from "@ignotum/contracts/runtime/sync";
-import {
-  ClientInfrastructureError,
-  InvalidMutationArguments,
-  reportClientError,
-} from "./errors.js";
+import { ClientInfrastructureError } from "./errors.js";
 import { isQuerySkip, type QuerySkip } from "./query.js";
 import { SyncClient, syncClientInternals, syncRuntime } from "./sync.js";
 
@@ -278,19 +274,10 @@ export const useMutation = <Args extends object | void, Success, Failure extends
       return syncRuntime.runPromise<SettledResult<Success, Failure>, ClientInfrastructureError>(
         Effect.gen(function* () {
           const client = yield* SyncClient;
-          const jsonArgs = yield* Effect.try({
-            try: () => encodeTransportObject(input),
-            catch: (cause) =>
-              InvalidMutationArguments.make({
-                cause,
-                function: functionPath,
-                message: `Mutation arguments for ${functionPath} contain an unsupported value.`,
-              }),
-          }).pipe(Effect.tapError(reportClientError));
           // SAFETY: generated function references bind the runtime path to the
           // declared public result types validated by the server executor.
           // oxlint-disable-next-line anti-slop/no-chained-type-assertions -- The untyped sync transport deliberately erases the generated reference's result parameters.
-          return (yield* client.mutate(functionPath, jsonArgs)) as unknown as SettledResult<
+          return (yield* client.mutate(functionPath, input)) as unknown as SettledResult<
             Success,
             Failure
           >;

package/src/client/index.ts

@@ -9,6 +9,13 @@ export const Result = { match: contractResult.match };
 export type Result<Value, Error extends ErrorValue> = SettledResult<Value, Error>;
 export type QueryResult<Value, Error extends ErrorValue> = ContractQueryResult<Value, Error>;
 export type { InternalServerError } from "@ignotum/contracts/runtime/result";
+export type {
+  FileFormat,
+  FileMetadata,
+  FileMimeType,
+  FileValue,
+} from "@ignotum/contracts/schema/file";
+export { Files } from "./files.js";
 export { useMutation, usePaginatedQuery, useQuery } from "./hooks.js";
 export type { PaginatedQueryOptions, PaginatedQueryValue, PaginationStatus } from "./hooks.js";
 export { Query } from "./query.js";

package/src/client/sync.ts

@@ -16,6 +16,7 @@ import * as BrowserCrypto from "@effect/platform-browser/BrowserCrypto";
 import { encodeCanonicalJson } from "@ignotum/contracts/json";
 import { type AppStateRevision } from "@ignotum/contracts/runtime/hosted";
 import { IdGenerator } from "@ignotum/shared/id";
+import { encodeTransportObject } from "@ignotum/contracts/runtime/sync";
 
 import type {
   ErrorValue,
@@ -25,7 +26,7 @@ import type {
 import { failureFromWire, pending, Result } from "@ignotum/contracts/runtime/result";
 import {
   ClientMessageJson,
-  DeploymentChangedCloseCode,
+  DeploymentCloseCode,
   InvocationId,
   ServerMessageJson,
   SubscriptionId,
@@ -41,11 +42,13 @@ import {
   ConnectionUnavailable,
   InvalidClientMessage,
   InvalidServerMessage,
-  ServerProtocolError,
+  ServerError,
+  InvalidMutationArguments,
   clientErrorReporterLayer,
   reportClientError,
 } from "./errors.js";
 import { syncPath } from "../internal/http-paths.js";
+import { applyFileGrants, prepareMutationArguments } from "./files.js";
 
 type Listener = () => void;
 type SocketWriter = (chunk: string) => Effect.Effect<void, Socket.SocketError>;
@@ -195,18 +198,22 @@ const makeQueryCache = (
   } satisfies QueryCache;
 };
 
-const resultFromWire = Effect.fn("SyncClient.resultFromWire")((wire: WireResult) =>
-  Effect.succeed(
-    wire.type === "Success"
-      ? Result.succeed(
-          wire.value === undefined ? undefined : decodeTransportValue(wire.value, wire.dates ?? []),
-        )
-      : failureFromWire(wire.error, wire.dates),
-  ),
+type SnapshotFiles = NonNullable<Extract<ServerMessage, { readonly type: "Snapshot" }>["files"]>;
+
+const resultFromWire = Effect.fn("SyncClient.resultFromWire")(
+  (wire: WireResult, files: SnapshotFiles = []) =>
+    Effect.succeed(
+      wire.type === "Success"
+        ? Result.succeed(
+            wire.value === undefined
+              ? undefined
+              : applyFileGrants(decodeTransportValue(wire.value, wire.dates ?? []), files),
+          )
+        : failureFromWire(wire.error, wire.dates),
+    ),
 );
 
-export const shouldReloadForCloseCode = (code: number): boolean =>
-  code === DeploymentChangedCloseCode;
+export const shouldReloadForCloseCode = (code: number): boolean => code === DeploymentCloseCode;
 
 const handshakesMatch = (first: SyncHandshake, next: SyncHandshake): boolean =>
   first.appId === next.appId &&
@@ -242,7 +249,8 @@ const socketUrl = (): string => {
 interface SyncClientService {
   readonly mutate: (
     functionAddress: FunctionAddress,
-    args: Schema.Json,
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Generated reference argument types are deliberately erased at the client transport boundary.
+    args: unknown,
   ) => Effect.Effect<IgnotumResult<unknown, ErrorValue>, ClientInfrastructureError>;
   readonly observe: (
     functionAddress: FunctionAddress,
@@ -256,7 +264,11 @@ interface PendingInvocation {
     ClientInfrastructureError
   >;
   readonly function: FunctionAddress;
-  readonly message: Extract<ClientMessage, { readonly type: "Invoke" }>;
+  readonly message: Extract<ClientMessage, { readonly type: "Invoke" | "Prepare" }>;
+  readonly prepared: Deferred.Deferred<
+    Extract<ServerMessage, { readonly type: "Preparation" }>["uploads"],
+    ClientInfrastructureError
+  >;
 }
 
 export class SyncClient extends Context.Service<SyncClient, SyncClientService>()(
@@ -319,25 +331,33 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
         }
         invocations = HashMap.remove(invocations, id);
         return reportClientError(error).pipe(
+          Effect.andThen(Deferred.fail(pendingInvocation.prepared, error)),
           Effect.andThen(Deferred.fail(pendingInvocation.deferred, error)),
           Effect.asVoid,
         );
       };
 
       const handleMessage = Effect.fn("SyncClient.handleMessage")(function* (
-        message: Exclude<ServerMessage, SyncHandshake | { readonly type: "DeploymentChanged" }>,
+        message: Exclude<ServerMessage, SyncHandshake | { readonly type: "Deployment" }>,
       ) {
         switch (message.type) {
           case "Snapshot": {
             const entry = queryCache.getById(message.id);
             if (entry === undefined) return;
-            yield* resultFromWire(message.result).pipe(
+            yield* resultFromWire(message.result, message.files ?? []).pipe(
               Effect.tap((result) =>
                 Effect.sync(() => queryCache.setResult(message.id, result, message.revision)),
               ),
             );
             return;
           }
+          case "Preparation": {
+            const pendingInvocation = HashMap.getUnsafe(invocations, message.id);
+            if (pendingInvocation !== undefined) {
+              yield* Deferred.succeed(pendingInvocation.prepared, message.uploads);
+            }
+            return;
+          }
           case "Result": {
             const pendingInvocation = HashMap.getUnsafe(invocations, message.id);
             if (pendingInvocation === undefined) return;
@@ -347,14 +367,14 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
             );
             return;
           }
-          case "ProtocolError": {
+          case "Error": {
             const error =
               message.operation === undefined
-                ? ServerProtocolError.make({
+                ? ServerError.make({
                     code: message.code,
                     message: message.message,
                   })
-                : ServerProtocolError.make({
+                : ServerError.make({
                     code: message.code,
                     message: message.message,
                     operation: message.operation,
@@ -428,7 +448,7 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
               ),
             );
             if (message.type === "Handshake") return yield* acceptHandshake(message);
-            if (message.type === "DeploymentChanged") {
+            if (message.type === "Deployment") {
               requestReload();
               return;
             }
@@ -488,31 +508,139 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
       const mutate: SyncClientService["mutate"] = Effect.fn("SyncClient.mutate")(
         function* (functionAddress, args) {
           const invocationId = yield* ids.generate(InvocationId);
+          const preparedArguments = yield* prepareMutationArguments(args).pipe(
+            Effect.provideService(IdGenerator, ids),
+            Effect.mapError((cause) =>
+              InvalidMutationArguments.make({
+                cause,
+                function: functionAddress,
+                message: `Mutation arguments for ${functionAddress} contain an unsupported file or value.`,
+              }),
+            ),
+            Effect.tapError(reportClientError),
+          );
+          const jsonArgs = yield* Effect.try({
+            try: () => encodeTransportObject(preparedArguments.value),
+            catch: (cause) =>
+              InvalidMutationArguments.make({
+                cause,
+                function: functionAddress,
+                message: `Mutation arguments for ${functionAddress} contain an unsupported value.`,
+              }),
+          }).pipe(Effect.tapError(reportClientError));
           const deferred = yield* Deferred.make<
             IgnotumResult<unknown, ErrorValue>,
             ClientInfrastructureError
           >();
-          const message: ClientMessage = {
+          const prepared = yield* Deferred.make<
+            Extract<ServerMessage, { readonly type: "Preparation" }>["uploads"],
+            ClientInfrastructureError
+          >();
+          const invokeMessage: Extract<ClientMessage, { readonly type: "Invoke" }> = {
             type: "Invoke",
             id: invocationId,
             kind: "Mutation",
             function: functionAddress,
-            args,
+            args: jsonArgs,
           };
+          const message: PendingInvocation["message"] =
+            preparedArguments.fileIds.length === 0
+              ? invokeMessage
+              : {
+                  type: "Prepare",
+                  id: invocationId,
+                  kind: "Mutation",
+                  function: functionAddress,
+                  args: jsonArgs,
+                  files: preparedArguments.fileIds,
+                };
           invocations = HashMap.set(invocations, invocationId, {
             deferred,
             function: functionAddress,
             message,
+            prepared,
           });
-          if (writer !== undefined) {
-            yield* sendWith(writer, message).pipe(
-              Effect.catchTags({
-                ConnectionUnavailable: reportClientError,
-                InvalidClientMessage: (error) => rejectInvocation(invocationId, error),
+          return yield* Effect.gen(function* () {
+            if (writer !== undefined) {
+              yield* sendWith(writer, message).pipe(
+                Effect.catchTags({
+                  ConnectionUnavailable: reportClientError,
+                  InvalidClientMessage: (error) => rejectInvocation(invocationId, error),
+                }),
+              );
+            }
+            if (message.type === "Prepare") {
+              const uploads = yield* Deferred.await(prepared);
+              const expected = new Set(message.files);
+              const received = new Set<string>();
+              for (const upload of uploads) {
+                if (!expected.has(upload.id) || received.has(upload.id)) {
+                  return yield* InvalidServerMessage.make({
+                    cause: new Error(`Unexpected prepared file '${upload.id}'.`),
+                    message: "The server returned invalid application file preparation data.",
+                  });
+                }
+                received.add(upload.id);
+                const file = preparedArguments.nativeFiles.get(upload.id);
+                if (file === undefined) {
+                  return yield* InvalidServerMessage.make({
+                    cause: new Error(`Missing native file '${upload.id}'.`),
+                    message: "The server prepared an unknown application file.",
+                  });
+                }
+                if (upload.url === undefined) continue;
+                const uploadUrl = upload.url;
+                const response = yield* Effect.tryPromise({
+                  try: () =>
+                    fetch(uploadUrl, {
+                      method: "PUT",
+                      body: file,
+                      headers: { "content-type": file.type },
+                    }),
+                  catch: (cause) =>
+                    ConnectionUnavailable.make({
+                      cause,
+                      message: `File '${file.name}' could not be uploaded.`,
+                    }),
+                });
+                if (!response.ok) {
+                  const detail = yield* Effect.promise(() => response.text());
+                  return yield* InvalidMutationArguments.make({
+                    cause: new Error(detail),
+                    function: functionAddress,
+                    message: `File '${file.name}' was rejected by application storage.`,
+                  });
+                }
+              }
+              if (received.size !== expected.size) {
+                return yield* InvalidServerMessage.make({
+                  cause: new Error("The server omitted a prepared file."),
+                  message: "The server returned incomplete application file preparation data.",
+                });
+              }
+              const pendingInvocation = HashMap.getUnsafe(invocations, invocationId);
+              if (pendingInvocation === undefined) return yield* Deferred.await(deferred);
+              invocations = HashMap.set(invocations, invocationId, {
+                ...pendingInvocation,
+                message: invokeMessage,
+              });
+              if (writer !== undefined) {
+                yield* sendWith(writer, invokeMessage).pipe(
+                  Effect.catchTags({
+                    ConnectionUnavailable: reportClientError,
+                    InvalidClientMessage: (error) => rejectInvocation(invocationId, error),
+                  }),
+                );
+              }
+            }
+            return yield* Deferred.await(deferred);
+          }).pipe(
+            Effect.tapError(() =>
+              Effect.sync(() => {
+                invocations = HashMap.remove(invocations, invocationId);
               }),
-            );
-          }
-          return yield* Deferred.await(deferred);
+            ),
+          );
         },
       );