ignotum 0.0.10 → 0.0.12

package/src/client/hooks.ts

@@ -12,6 +12,8 @@ import {
 import { encodeTransportObject } from "@ignotum/contracts/runtime/sync";
 import { ClientInfrastructureError } from "./errors.js";
 import { isQuerySkip, type QuerySkip } from "./query.js";
+// oxlint-disable-next-line anti-slop-effect/no-service-constructor-imports -- Each mounted pagination hook owns and releases its page observers.
+import { makePageObservers } from "./page-observers.js";
 import { SyncClient, syncClientInternals, syncRuntime } from "./sync.js";
 
 // @effect-diagnostics-next-line missingPipeableSignature:off React hooks are not pipeable functions.
@@ -158,6 +160,18 @@ export function usePaginatedQuery<Args extends object, Item, Failure extends Err
     readonly result: QueryResult<PaginatedQueryValue<Item>, Failure> | ClientInfrastructureError;
   }>(() => ({ identity, result: pending() }));
   const loadMore = useCallback(() => setRequestedPages((count) => count + 1), []);
+  const pages = useMemo(
+    () =>
+      makePageObservers(
+        () => setRefresh((version) => version + 1),
+        (release) => {
+          syncRuntime.runFork(release);
+        },
+      ),
+    [identity, pageSize],
+  );
+
+  useEffect(() => () => pages.release(), [pages]);
 
   useDebugValue({ args: input, function: functionPath, result: state.result });
 
@@ -170,12 +184,11 @@ export function usePaginatedQuery<Args extends object, Item, Failure extends Err
     if (skipped) return;
 
     let active = true;
-    const releases: Array<() => void> = [];
+    const usedPages = new Set<string>();
 
     void syncRuntime
       .runPromise(
         Effect.gen(function* () {
-          const client = yield* SyncClient;
           const items: Item[] = [];
           let cursor: PaginationOptions["cursor"] = null;
 
@@ -184,18 +197,9 @@ export function usePaginatedQuery<Args extends object, Item, Failure extends Err
               ...input,
               pagination: { cursor, pageSize },
             });
-            const observer = yield* client.observe(functionPath, pageArgs);
-            if (!active) {
-              yield* observer.release;
-              return;
-            }
-            const releaseSubscription = observer.subscribe(() => {
-              if (active) setRefresh((version) => version + 1);
-            });
-            releases.push(() => {
-              releaseSubscription();
-              syncRuntime.runFork(observer.release);
-            });
+            usedPages.add(syncClientInternals.queryIdentity(functionPath, pageArgs));
+            const observer = yield* pages.observe(functionPath, pageArgs);
+            if (!active || observer === undefined) return;
 
             const snapshot = observer.getSnapshot();
             if (Schema.is(ClientInfrastructureError)(snapshot)) {
@@ -240,7 +244,13 @@ export function usePaginatedQuery<Args extends object, Item, Failure extends Err
             identity,
             result: RuntimeResult.succeed({ items, loadMore, status: "CanLoadMore" }),
           });
-        }),
+        }).pipe(
+          Effect.ensuring(
+            Effect.sync(() => {
+              if (active) pages.retain(usedPages);
+            }),
+          ),
+        ),
       )
       .catch((error) => {
         if (active && Schema.is(ClientInfrastructureError)(error)) {
@@ -250,9 +260,8 @@ export function usePaginatedQuery<Args extends object, Item, Failure extends Err
 
     return () => {
       active = false;
-      for (const release of releases) release();
     };
-  }, [functionPath, identity, loadMore, pageSize, refresh, requestedPages, skipped]);
+  }, [functionPath, identity, loadMore, pageSize, pages, refresh, requestedPages, skipped]);
 
   if (skipped || state.identity !== identity) return pending();
   const result = state.result;

package/src/client/page-observers.ts

@@ -0,0 +1,77 @@
+import { Effect, Schema } from "effect";
+
+import type { FunctionAddress } from "@ignotum/contracts/runtime/sync";
+import { SyncClient, syncClientInternals } from "./sync.js";
+import type { ClientInfrastructureError } from "./errors.js";
+
+type QueryObserver = Effect.Success<ReturnType<SyncClient["Service"]["observe"]>>;
+
+interface PageEntry {
+  readonly acquire: Effect.Effect<QueryObserver | undefined, ClientInfrastructureError, SyncClient>;
+  release: (() => void) | undefined;
+  released: boolean;
+}
+
+// @effect-diagnostics-next-line missingPipeableSignature:off This hook-owned lifecycle takes two callbacks, not a data argument.
+export const makePageObservers = (
+  onChange: () => void,
+  releaseObserver: (release: Effect.Effect<void>) => void,
+) => {
+  const pages = new Map<string, PageEntry>();
+  let disposed = false;
+
+  const releaseEntry = (entry: PageEntry) => {
+    entry.released = true;
+    entry.release?.();
+  };
+
+  const observe = Effect.fn("PageObservers.observe")(function* (
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+  ) {
+    if (disposed) return;
+    const key = syncClientInternals.queryIdentity(functionAddress, args);
+    const existing = pages.get(key);
+    if (existing !== undefined) return yield* existing.acquire;
+
+    const entry: PageEntry = {
+      acquire: yield* Effect.cached(
+        Effect.gen(function* () {
+          const client = yield* SyncClient;
+          const observer = yield* client.observe(functionAddress, args);
+          if (entry.released) {
+            releaseObserver(observer.release);
+            return;
+          }
+          const unsubscribe = observer.subscribe(onChange);
+          entry.release = () => {
+            unsubscribe();
+            releaseObserver(observer.release);
+          };
+          return observer;
+        }),
+      ),
+      release: undefined,
+      released: false,
+    };
+    pages.set(key, entry);
+    return yield* entry.acquire;
+  });
+
+  return {
+    observe,
+    retain: (keys: ReadonlySet<string>) => {
+      for (const [key, entry] of pages) {
+        if (keys.has(key)) continue;
+        pages.delete(key);
+        releaseEntry(entry);
+      }
+    },
+    release: () => {
+      if (disposed) return;
+      disposed = true;
+      for (const entry of pages.values()) releaseEntry(entry);
+      pages.clear();
+    },
+  };
+};

package/src/client/sync.ts

@@ -75,11 +75,10 @@ type QueryLifecycleMessage = Extract<ClientMessage, { readonly type: "Subscribe"
 interface QueryCache {
   readonly entries: () => Iterable<QueryEntry>;
   readonly getById: (id: SubscriptionId) => QueryEntry | undefined;
-  readonly setError: (id: SubscriptionId, error: ClientInfrastructureError) => void;
   readonly setResult: (
     id: SubscriptionId,
-    result: QueryResult<unknown, ErrorValue>,
-    revision: AppStateRevision,
+    result: QueryResult<unknown, ErrorValue> | ClientInfrastructureError,
+    revision?: AppStateRevision,
   ) => void;
   readonly observe: (
     functionAddress: FunctionAddress,
@@ -102,7 +101,7 @@ const makeQueryCache = (
   sendLifecycleMessage: (message: QueryLifecycleMessage) => Effect.Effect<void>,
 ) => {
   const queries = new Map<string, QueryEntry>();
-  const queryKeysById = new Map<SubscriptionId, string>();
+  const queriesById = new Map<SubscriptionId, QueryEntry>();
 
   const observe = Effect.fn("SyncClient.QueryCache.observe")(function* (
     functionAddress: FunctionAddress,
@@ -123,7 +122,7 @@ const makeQueryCache = (
         subscriptionId: yield* allocateId,
       };
       queries.set(key, created);
-      queryKeysById.set(created.subscriptionId, key);
+      queriesById.set(created.subscriptionId, created);
       yield* sendLifecycleMessage(subscribeMessage(created));
       entry = created;
     }
@@ -157,7 +156,7 @@ const makeQueryCache = (
         }
 
         queries.delete(key);
-        queryKeysById.delete(observed.subscriptionId);
+        queriesById.delete(observed.subscriptionId);
         yield* sendLifecycleMessage({
           type: "Unsubscribe",
           id: observed.subscriptionId,
@@ -168,28 +167,15 @@ const makeQueryCache = (
 
   return {
     entries: () => queries.values(),
-    getById: (id: SubscriptionId) => {
-      const key = queryKeysById.get(id);
-      return key === undefined ? undefined : queries.get(key);
-    },
+    getById: (id: SubscriptionId) => queriesById.get(id),
     observe,
-    setError: (id, error) => {
-      const key = queryKeysById.get(id);
-      const entry = key === undefined ? undefined : queries.get(key);
-      if (entry === undefined) return;
-      entry.result = error;
-      for (const listener of entry.listeners) {
-        listener();
-      }
-    },
-    setResult: (id, result, revision) => {
-      const key = queryKeysById.get(id);
-      const entry = key === undefined ? undefined : queries.get(key);
+    setResult: (id, result, revision?: AppStateRevision) => {
+      const entry = queriesById.get(id);
       if (entry === undefined) return;
-      if (entry.revision !== undefined && revision < entry.revision) {
-        return;
+      if (revision !== undefined) {
+        if (entry.revision !== undefined && revision < entry.revision) return;
+        entry.revision = revision;
       }
-      entry.revision = revision;
       entry.result = result;
       for (const listener of entry.listeners) {
         listener();
@@ -202,15 +188,21 @@ type SnapshotFiles = NonNullable<Extract<ServerMessage, { readonly type: "Snapsh
 
 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),
-    ),
+    Effect.try({
+      try: () =>
+        wire.type === "Success"
+          ? Result.succeed(
+              wire.value === undefined
+                ? undefined
+                : applyFileGrants(decodeTransportValue(wire.value, wire.dates ?? []), files),
+            )
+          : failureFromWire(wire.error, wire.dates),
+      catch: (cause) =>
+        InvalidServerMessage.make({
+          cause,
+          message: "The server returned an invalid function result.",
+        }),
+    }),
 );
 
 export const shouldReloadForCloseCode = (code: number): boolean => code === DeploymentCloseCode;
@@ -344,10 +336,17 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
           case "Snapshot": {
             const entry = queryCache.getById(message.id);
             if (entry === undefined) return;
+            if (entry.revision !== undefined && message.revision < entry.revision) return;
             yield* resultFromWire(message.result, message.files ?? []).pipe(
               Effect.tap((result) =>
                 Effect.sync(() => queryCache.setResult(message.id, result, message.revision)),
               ),
+              Effect.catchTags({
+                InvalidServerMessage: (error) => {
+                  queryCache.setResult(message.id, error, message.revision);
+                  return reportClientError(error);
+                },
+              }),
             );
             return;
           }
@@ -361,9 +360,14 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
           case "Result": {
             const pendingInvocation = HashMap.getUnsafe(invocations, message.id);
             if (pendingInvocation === undefined) return;
-            invocations = HashMap.remove(invocations, message.id);
             yield* resultFromWire(message.result).pipe(
-              Effect.flatMap((result) => Deferred.succeed(pendingInvocation.deferred, result)),
+              Effect.flatMap((result) => {
+                invocations = HashMap.remove(invocations, message.id);
+                return Deferred.succeed(pendingInvocation.deferred, result);
+              }),
+              Effect.catchTags({
+                InvalidServerMessage: (error) => rejectInvocation(message.id, error),
+              }),
             );
             return;
           }
@@ -382,7 +386,7 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
             if (message.operation?.type === "Invocation") {
               yield* rejectInvocation(message.operation.id, error);
             } else if (message.operation?.type === "Subscription") {
-              queryCache.setError(message.operation.id, error);
+              queryCache.setResult(message.operation.id, error);
               yield* reportClientError(error);
             } else {
               yield* reportClientError(error);
@@ -573,6 +577,7 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
               const uploads = yield* Deferred.await(prepared);
               const expected = new Set(message.files);
               const received = new Set<string>();
+              const transfers: Array<{ readonly file: File; readonly url: string }> = [];
               for (const upload of uploads) {
                 if (!expected.has(upload.id) || received.has(upload.id)) {
                   return yield* InvalidServerMessage.make({
@@ -589,28 +594,7 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
                   });
                 }
                 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.`,
-                  });
-                }
+                transfers.push({ file, url: upload.url });
               }
               if (received.size !== expected.size) {
                 return yield* InvalidServerMessage.make({
@@ -618,6 +602,34 @@ export class SyncClient extends Context.Service<SyncClient, SyncClientService>()
                   message: "The server returned incomplete application file preparation data.",
                 });
               }
+              yield* Effect.forEach(
+                transfers,
+                Effect.fn("SyncClient.uploadFile")(function* ({ file, url }) {
+                  const response = yield* Effect.tryPromise({
+                    try: (signal) =>
+                      fetch(url, {
+                        method: "PUT",
+                        body: file,
+                        headers: { "content-type": file.type },
+                        signal,
+                      }),
+                    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.`,
+                    });
+                  }
+                }),
+                { concurrency: 3, discard: true },
+              );
               const pendingInvocation = HashMap.getUnsafe(invocations, invocationId);
               if (pendingInvocation === undefined) return yield* Deferred.await(deferred);
               invocations = HashMap.set(invocations, invocationId, {

package/src/dev-runtime/functions.ts

@@ -6,12 +6,21 @@ import {
   type FunctionKind,
   type FunctionResolutionError,
 } from "@ignotum/contracts/runtime/functions";
-import { type RuntimeSchemaDefinition } from "@ignotum/contracts/runtime/schema";
+import {
+  getFunctionEnvironment,
+  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 {
+  emptyEnv,
+  isDefinedEnv,
+  type DefinedEnv,
+  type EnvironmentType,
+} from "@ignotum/contracts/schema";
 import {
   FunctionAddress,
   apiFunctionParts,
@@ -21,7 +30,19 @@ import {
   type WireResult,
 } from "@ignotum/contracts/runtime/sync";
 import { FunctionRuntime } from "@ignotum/runtime/functions";
-import { Cause, Context, Effect, Layer, Path, Predicate, Schema, Semaphore } from "effect";
+import {
+  Cause,
+  Context,
+  Effect,
+  FileSystem,
+  Layer,
+  Path,
+  Predicate,
+  Ref,
+  Result,
+  Schema,
+  Semaphore,
+} from "effect";
 import type { ViteDevServer } from "vite";
 import { normalizePath } from "vite";
 
@@ -31,6 +52,11 @@ import {
   type FunctionArguments,
   type RuntimeFunctionDefinition as InternalRuntimeFunctionDefinition,
 } from "../internal/function-definition.js";
+import {
+  EnvironmentConfigurationInvalid,
+  loadEnvironment,
+  type LoadedEnvironment,
+} from "../cli/environment.js";
 
 export { FunctionUnavailable, InvalidArguments, UnknownFunction, WrongFunctionKind };
 export type { FunctionArguments, FunctionKind };
@@ -38,10 +64,78 @@ export type { FunctionArguments, FunctionKind };
 export type RuntimeHandlerContext = LocalMutationContext | LocalQueryContext;
 export type RuntimeFunctionDefinition = InternalRuntimeFunctionDefinition<RuntimeHandlerContext>;
 
+const loadDevelopmentEnvironment = Effect.fn("DevelopmentEnvironment.load")(function* (
+  server: ViteDevServer,
+  appDirectory: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const definitionPath = path.join(appDirectory, "server", "env.ts");
+  const hasDefinition = yield* fileSystem.exists(definitionPath);
+  if (!hasDefinition) return yield* loadEnvironment(appDirectory, emptyEnv, false);
+  const loaded = yield* Effect.tryPromise({
+    try: () => server.ssrLoadModule(normalizePath(definitionPath)),
+    catch: () =>
+      EnvironmentConfigurationInvalid.make({
+        message: "Ignotum could not load server/env.ts.",
+        path: definitionPath,
+      }),
+  });
+  if (!Predicate.isObject(loaded.default) || !isDefinedEnv(loaded.default)) {
+    return yield* EnvironmentConfigurationInvalid.make({
+      message: "The default export from server/env.ts is not an Ignotum environment.",
+      path: definitionPath,
+    });
+  }
+  return yield* loadEnvironment(appDirectory, loaded.default, true);
+});
+
+export class DevelopmentEnvironment extends Context.Service<
+  DevelopmentEnvironment,
+  {
+    readonly reload: Effect.Effect<void, unknown>;
+    readonly snapshot: Effect.Effect<LoadedEnvironment, unknown>;
+  }
+>()("ignotum/dev-runtime/functions/DevelopmentEnvironment") {
+  static layer(server: ViteDevServer, appDirectory: string) {
+    return Layer.effect(
+      DevelopmentEnvironment,
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const load = loadDevelopmentEnvironment(server, appDirectory).pipe(
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(Path.Path, path),
+        );
+        const initial = yield* load;
+        const current = yield* Ref.make<Result.Result<LoadedEnvironment, unknown>>(
+          Result.succeed(initial),
+        );
+        const fromResult = Result.match({
+          onFailure: Effect.fail,
+          onSuccess: Effect.succeed,
+        });
+        const reload = load.pipe(
+          Effect.result,
+          Effect.flatMap((result) =>
+            Ref.set(current, result).pipe(Effect.andThen(fromResult(result))),
+          ),
+          Effect.asVoid,
+        );
+        return DevelopmentEnvironment.of({
+          reload,
+          snapshot: Ref.get(current).pipe(Effect.flatMap(fromResult)),
+        });
+      }),
+    );
+  }
+}
+
 export interface ResolvedFunction {
   readonly definition: RuntimeFunctionDefinition;
   readonly args: FunctionArguments;
   readonly schema: RuntimeSchemaDefinition;
+  readonly environment?: Readonly<EnvironmentType<DefinedEnv>>;
 }
 
 export class FunctionRegistry extends Context.Service<
@@ -59,6 +153,7 @@ export class FunctionRegistry extends Context.Service<
       FunctionRegistry,
       Effect.gen(function* () {
         const path = yield* Path.Path;
+        const developmentEnvironment = yield* DevelopmentEnvironment;
         return FunctionRegistry.of({
           resolve: Effect.fn("FunctionRegistry.resolve")(function* (functionAddress, kind, args) {
             const { functionName, moduleName } = apiFunctionParts(functionAddress);
@@ -84,6 +179,14 @@ export class FunctionRegistry extends Context.Service<
               });
             }
             const definition = inspected.definition;
+            const environmentDefinition = getFunctionEnvironment(candidate);
+            if (environmentDefinition === undefined) {
+              return yield* FunctionUnavailable.make({
+                cause: new Error(`${functionAddress} has no environment binding.`),
+                function: functionAddress,
+                message: `Could not load ${functionAddress}.`,
+              });
+            }
 
             if (definition._tag !== kind) {
               return yield* WrongFunctionKind.make({
@@ -105,7 +208,22 @@ export class FunctionRegistry extends Context.Service<
               ),
             );
 
-            return { args: decodedArgs, definition, schema: inspected.schema };
+            const loadedEnvironment = yield* developmentEnvironment.snapshot.pipe(
+              Effect.mapError((cause) =>
+                FunctionUnavailable.make({
+                  cause,
+                  function: functionAddress,
+                  message: `Could not load ${functionAddress}.`,
+                }),
+              ),
+            );
+
+            return {
+              args: decodedArgs,
+              definition,
+              environment: loadedEnvironment.value,
+              schema: inspected.schema,
+            };
           }),
         });
       }),
@@ -166,7 +284,12 @@ export class FunctionExecutor extends Context.Service<
       return FunctionExecutor.of({
         execute: Effect.fn("FunctionExecutor.execute")(function* (functionAddress, kind, resolved) {
           const invoke = (context: RuntimeHandlerContext) =>
-            Effect.gen(() => resolved.definition.handler(context, resolved.args)).pipe(
+            Effect.gen(() =>
+              resolved.definition.handler(
+                Object.freeze({ ...context, env: resolved.environment ?? Object.freeze({}) }),
+                resolved.args,
+              ),
+            ).pipe(
               Effect.matchEffect({
                 onFailure: (error) => encodeFailure(resolved.definition, error),
                 onSuccess: (value) => encodeSuccess(resolved.definition, value),