@phreshos/server 0.1.22 → 0.1.24

package/README.md

@@ -136,6 +136,9 @@ A Program owns its scoped Process capability:
 const processes = await program.process.list()
 const process = await program.process.find("worker")
 const created = await program.process.create({ name: "worker" })
+for await (const event of program.process.run({ name: "temporary" }, { signal })) {
+  // started, output, exited
+}
 const shared = await program.process.findOrCreate({
   name: "shared-server",
   server: true,
@@ -143,6 +146,11 @@ const shared = await program.process.findOrCreate({
 })
 ```
 
+`run()` creates exactly one Process and yields its ordered `started`, `output`,
+and `exited` lifecycle. Aborting its signal, returning early, or losing the
+calling Server exits that Process; `create()` remains independent of the
+caller.
+
 `findOrCreate()` is atomic at the authoritative Core. Concurrent equivalent
 launches converge on one named Process; a different launch for that name
 rejects instead of reconfiguring the existing Process.
@@ -172,7 +180,7 @@ if (program.hasAgent) console.log(await program.agent())
 asset-hosting address. Omitting the size selects `medium`.
 
 Installed Programs may persist one ordinary Process launch for the next system
-startup. This capability exists only in the Server SDK:
+startup through the shared Program interface:
 
 ```ts
 await program.startup.enable({

package/dist/domain.d.ts

@@ -74,11 +74,26 @@ export interface ProgramProcess extends Omit<CoreProgramProcess, "list" | "first
     find(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this Program. */
     create(launch?: Launch): Promise<Process>;
+    /** Runs one Process for exactly as long as its lifecycle iterator remains open. */
+    run(launch?: Launch, options?: ProgramProcessRunOptions): AsyncGenerator<ProgramProcessRunEvent, void, void>;
     /** Finds the named Process or atomically creates it with the same resolved launch. */
     findOrCreate(launch: Launch & Readonly<{
         name: string;
     }>): Promise<Process>;
 }
+export type ProgramProcessRunEvent = Readonly<{
+    event: "started";
+    process: Process;
+}> | (Readonly<{
+    event: "output";
+}> & ProgramCommandChunk) | Readonly<{
+    event: "exited";
+    process: Process;
+    exit: Exit;
+}>;
+export type ProgramProcessRunOptions = Readonly<{
+    signal?: AbortSignal;
+}>;
 /** Server-visible Process handle. */
 export interface Process<Events extends object = {}> extends CoreProcess<Events> {
     /** Permanent handle to this Process's Server. */

package/dist/domain.js

@@ -134,6 +134,11 @@ class ProgramProcessHandle {
         const answer = await wire.request(["program-process-create", this.address, launch]);
         return process(answer[0]);
     }
+    async *run(launch = {}, options = {}) {
+        for await (const value of wire.stream(["run", this.address, launch], undefined, options.signal)) {
+            yield processRunEvent(value);
+        }
+    }
     async findOrCreate(launch) {
         const answer = await wire.request(["program-process-find-or-create", this.address, launch]);
         return process(answer[0]);
@@ -143,6 +148,21 @@ class ProgramProcessHandle {
         return answer[0];
     }
 }
+function processRunEvent(value) {
+    const event = value;
+    if (event?.event === "started" && event.process) {
+        return Object.freeze({ event: "started", process: process(event.process) });
+    }
+    if (event?.event === "output" && (event.stream === "stdout" || event.stream === "stderr") && typeof event.text === "string") {
+        return Object.freeze({ event: "output", stream: event.stream, text: event.text });
+    }
+    if (event?.event === "exited" && event.process) {
+        const code = typeof event.exit?.code === "number" ? event.exit.code : null;
+        const signal = typeof event.exit?.signal === "string" ? event.exit.signal : null;
+        return Object.freeze({ event: "exited", process: process(event.process), exit: exit(code, signal) });
+    }
+    throw new Error("The System returned an invalid Process run event");
+}
 /** Internal transport address for a Program handle created by this SDK. */
 export function programAddress(value) {
     if (!(value instanceof ProgramHandle))

package/dist/main.d.ts

@@ -5,5 +5,5 @@ export { type ProgramStartup } from "./startup.js";
 export { type Storage } from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess } from "./domain.js";
-export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, ServerTraffic, System, SystemProcess, SystemProcessEntity, SystemProcessEntityEvents, SystemProgram, SystemProgramEntity, SystemProgramProcess, SystemProgramProcessEvents, SystemEndpointEntity, SystemServerEntity, SystemClientEntity, ClientDescription, SystemProcessEvents, SystemProcessExit, SystemProgramEvents, SystemProgramUninstall, ProgramDescription, ServerDescription, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, ThemedValue, WritableAppearance, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./domain.js";
+export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, ServerTraffic, System, SystemProcess, SystemProcessEntity, SystemProcessEntityEvents, SystemProgram, SystemProgramEntity, SystemProgramProcess, SystemProgramProcessEvents, SystemEndpointEntity, SystemServerEntity, SystemClientEntity, ClientDefinition, SystemProcessEvents, SystemProcessExit, SystemProgramEvents, SystemProgramUninstall, ProgramDefinition, ServerDefinition, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, ThemedValue, WritableAppearance, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/system.js

@@ -11,6 +11,10 @@ class ServerSystem {
     program = new ServerSystemProgram();
     process = new ServerSystemProcess();
     uploads = uploads;
+    async forceCreateProgram(source) {
+        const answer = await wire.request(["host-program-force-create", source]);
+        return program(answer[0]);
+    }
     service(key) { return prepareService(key); }
 }
 class ServerSystemProgram extends Events {

package/dist/wire.d.ts

@@ -20,7 +20,7 @@ declare class Wire {
     request(values: unknown[], timeout?: number): Promise<unknown>;
     requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
     /** Opens one long-running system operation and yields its ordered values. */
-    stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
+    stream(values: unknown[], timeout?: number, signal?: AbortSignal): AsyncIterableIterator<unknown>;
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity(): Promise<{
         process: string;

package/dist/wire.js

@@ -74,7 +74,7 @@ class Wire {
         });
     }
     /** Opens one long-running system operation and yields its ordered values. */
-    stream(values, timeout = defaultTimeout) {
+    stream(values, timeout = defaultTimeout, signal) {
         const wire = this;
         return (async function* () {
             const question = randomUUID();
@@ -90,6 +90,15 @@ class Wire {
                     state.wake = null;
                 }, timeout)
             };
+            const abort = () => {
+                state.failure = signal?.reason instanceof Error ? signal.reason : new Error("The operation was cancelled");
+                state.wake?.();
+                state.wake = null;
+            };
+            if (signal?.aborted)
+                abort();
+            else
+                signal?.addEventListener("abort", abort, { once: true });
             wire.send("boundary", "expect", question);
             wire.streams.set(question, state);
             wire.send("end-host", "stream", question, ...values);
@@ -107,6 +116,7 @@ class Wire {
                 }
             }
             finally {
+                signal?.removeEventListener("abort", abort);
                 clearTimeout(state.timer);
                 wire.streams.delete(question);
                 wire.send("boundary", "forget", question);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-    "version": "0.1.22",
+    "version": "0.1.24",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.21"
+    "@phreshos/core": "^0.1.23"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-        "@phreshos/core": "^0.1.21",
+        "@phreshos/core": "^0.1.23",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }