@phreshos/server 0.1.2 → 0.1.4

package/dist/channel.d.ts

@@ -1,8 +1,9 @@
-import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
+import type { Channel as CoreChannel, ChannelMessage, Cleanup, ServerServiceDefinition } from "@phreshos/core";
+import { type Endpoint } from "./domain.js";
 /** Handles one question addressed to the current Server. */
 export type Answerer<Payload = unknown, Result = undefined> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
 /** Events and questions explicitly accepted by the current Server. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events> {
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint, ServerServiceDefinition> {
     /** Registers one answerer; omitting its return produces `undefined`. */
     answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
 }

package/dist/channel.js

@@ -1,6 +1,7 @@
 import { endpoint } from "./domain.js";
 import Events from "./events.js";
 import wire from "./wire.js";
+import { disableCurrentService, enableCurrentService } from "./service.js";
 class ServerChannel extends Events {
     constructor() {
         super((event, listener, impossible) => wire.on("end-end", event, value => listener(message(value)), null, impossible), observer => wire.onAll("end-end", (event, value) => {
@@ -11,6 +12,8 @@ class ServerChannel extends Events {
     publish(event, payload = undefined) {
         wire.send("end-host", "emit", event, payload);
     }
+    async enableService(definition) { await enableCurrentService(definition); }
+    async disableService() { await disableCurrentService(); }
     answer(event, answerer) {
         return wire.answer("end-end", event, value => answerer(message(value)));
     }

package/dist/current.d.ts

@@ -1,10 +1,9 @@
-import type { Channel as CoreChannel } from "@phreshos/core";
-import { type Answerer } from "./channel.js";
-import { Client, type Process, type Program } from "./domain.js";
+import { type Answerer, type Channel } from "./channel.js";
+import { Client, type Process, type Program, type Server } from "./domain.js";
 /** The current Process's canonical Client handle. */
 export type CurrentClient<Events extends object = {}> = Client<Events>;
 /** Current Server context: its inbound Channel, owner hierarchy, and paired Client. */
-export interface Current<Events extends object = {}> extends CoreChannel<Events> {
+export interface Current<Events extends object = {}> extends Channel<Events>, Pick<Server, "service"> {
     /** The same Client handle exposed by the current Process. */
     readonly client: CurrentClient;
     /** Registers one answerer; omitting its return produces `undefined`. */

package/dist/current.js

@@ -1,6 +1,7 @@
 import { channel } from "./channel.js";
 import { Client, TrafficHandle, bindEvents, endpointEvents, process, program, window } from "./domain.js";
 import wire from "./wire.js";
+import { endpointService } from "./service.js";
 const ClientBase = Client;
 class CurrentClientHandle extends ClientBase {
     owner;
@@ -24,6 +25,7 @@ class CurrentClientHandle extends ClientBase {
         await wire.request(["start-endpoint", undefined, "client", overrides]);
     }
     async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
+    service() { return endpointService(null, "client"); }
 }
 let ownerPromise = null;
 let currentClient;
@@ -64,6 +66,7 @@ class ServerCurrent {
         return answer[0];
     }
     async stop() { await wire.request(["stop-current"]); }
+    service() { return endpointService(null, "server"); }
 }
 function bindChannel(target, source) {
     Object.assign(target, {
@@ -71,7 +74,9 @@ function bindChannel(target, source) {
         subscribe: source.subscribe.bind(source),
         waitFor: source.waitFor.bind(source),
         events: source.events.bind(source),
-        observe: source.observe.bind(source)
+        observe: source.observe.bind(source),
+        enableService: source.enableService.bind(source),
+        disableService: source.disableService.bind(source)
     });
 }
 /** Inbound events, owner hierarchy, and paired Client for the current Server. */

package/dist/domain.js

@@ -7,6 +7,7 @@ import { area, sql, store } from "./storage.js";
 import startup, {} from "./startup.js";
 import permissions from "./permissions.js";
 import wire from "./wire.js";
+import { endpointService } from "./service.js";
 const handles = new HandleRegistry();
 const ProgramBase = CoreProgram;
 const ProcessBase = CoreProcess;
@@ -66,10 +67,6 @@ class ProgramHandle extends ProgramBase {
         const answer = await wire.request(["create-process", this.address, launch]);
         return process(answer[0]);
     }
-    async apiDocs() {
-        const answer = await wire.request(["api-docs", this.address]);
-        return answer[0];
-    }
     async icon(size = "medium") {
         const answer = await wire.request(["icon", this.address, size]);
         return new Blob([Uint8Array.from(answer[0])], { type: "image/png" });
@@ -201,6 +198,7 @@ class ServerHandle extends ServerBase {
     }
     async start() { await wire.request(["start-endpoint", this.owner.address, "server"]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "server"]); }
+    service() { return endpointService(this.owner.address, "server"); }
     async waitReady(timeout) {
         await wire.request(["wait-ready", this.owner.address], timeout);
     }
@@ -247,6 +245,7 @@ class ClientHandle extends ClientBase {
         await wire.request(["start-endpoint", this.owner.address, "client", overrides]);
     }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "client"]); }
+    service() { return endpointService(this.owner.address, "client"); }
 }
 class WindowHandle extends Events {
     target;

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{
@@ -37,8 +37,6 @@ type Description = Readonly<{
     version?: string;
     /** Short human-readable Program description. */
     description?: string;
-    /** Path to the Program-authored API entry document. */
-    apiDocs?: string;
     /** Absolute validated PNG source used to derive the Program's hosted icon sizes. */
     icon?: string;
     /** Absolute directory used for the Program's persistent storage. */
@@ -107,6 +105,18 @@ export interface Host<Events extends object = {}> extends Subscribable<HostEvent
     processes(): Promise<Process[]>;
     /** Returns the live Process with the given runtime identity. */
     getProcess(identity: string): Promise<Process>;
+    /** Returns a stable handle for one exact Server service identity. */
+    service<ServiceEvents extends object = {}>(key: {
+        program: string;
+        endpoint: "server";
+        name: string;
+    }): ServerServiceHandler<ServiceEvents>;
+    /** Returns a stable handle for one exact Client service identity. */
+    service<ServiceEvents extends object = {}>(key: {
+        program: string;
+        endpoint: "client";
+        name: string;
+    }): ClientServiceHandler<ServiceEvents>;
 }
 /** Authoritative system capabilities for the currently executing Server. */
 export declare const host: Host;

package/dist/host.js

@@ -4,6 +4,7 @@ import serve from "./served.js";
 import ServerTheme from "./theme.js";
 import { ServerDesktopWallpaper, ServerSignInWallpaper } from "./wallpaper.js";
 import wire from "./wire.js";
+import { service as serviceHandle } from "./service.js";
 class ServerHost extends Events {
     theme = new ServerTheme();
     signInWallpaper = new ServerSignInWallpaper();
@@ -35,6 +36,9 @@ class ServerHost extends Events {
         const answer = await wire.request(["process", identity]);
         return process(answer[0]);
     }
+    service(key) {
+        return serviceHandle(key);
+    }
 }
 function hostEvent(event, values) {
     if (event === "endpointStart" || event === "endpointStop")

package/dist/main.d.ts

@@ -2,5 +2,6 @@ export { host, type Host, type ClientDescription, type HostEvents, type HostProc
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea } from "./domain.js";
 export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, 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, ProgramPermissions, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowLayer, WindowState, WindowSurface, WindowSurfaceEasing, WindowSurfaceSettings, WindowSurfaceTransaction } from "@phreshos/core";

package/dist/main.js

@@ -2,4 +2,5 @@ export { host } from "./host.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export {} from "./startup.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

@@ -0,0 +1,14 @@
+import { type ClientServiceHandler, type ServerServiceDefinition, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
+import type { HandleAddress } from "./domain.js";
+export declare function service<EventsMap extends object = {}>(key: ServiceKey & {
+    endpoint: "server";
+}): ServerServiceHandler<EventsMap>;
+export declare function service<EventsMap extends object = {}>(key: ServiceKey & {
+    endpoint: "client";
+}): ClientServiceHandler<EventsMap>;
+export declare function service(key: ServiceKey): ServiceHandler;
+export declare function enableCurrentService(definition: ServerServiceDefinition): Promise<void>;
+export declare function disableCurrentService(): Promise<void>;
+export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "server"): Promise<ServerServiceHandler<EventsMap> | null>;
+export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "client"): Promise<ClientServiceHandler<EventsMap> | null>;
+export declare function endpointService(target: HandleAddress | null, endpoint: "server" | "client"): Promise<ServiceHandler | null>;

package/dist/service.js

@@ -0,0 +1,127 @@
+import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, isServiceKey } from "@phreshos/core";
+import { randomUUID } from "node:crypto";
+import Deadline from "./deadline.js";
+import Events from "./events.js";
+import HandleRegistry from "./handle-registry.js";
+import wire from "./wire.js";
+const handles = new HandleRegistry();
+const ServerServiceBase = CoreServerServiceHandler;
+const ClientServiceBase = CoreClientServiceHandler;
+class ServerChannelHandle extends Events {
+    key;
+    constructor(key) {
+        super(...serviceEvents(key, "channel"));
+        this.key = key;
+    }
+    publish(event, payload = undefined) {
+        wire.send("end-host", "service-send", this.key, event, payload);
+    }
+    async ask(event, payload = undefined) {
+        return await this.askWithin(new Deadline(), event, payload);
+    }
+    timeout(milliseconds) {
+        return {
+            ask: (event, payload = undefined) => {
+                return this.askWithin(new Deadline(milliseconds), event, payload);
+            }
+        };
+    }
+    async askWithin(deadline, event, payload) {
+        const identity = await wire.identity();
+        const address = `server:${identity.process}:${randomUUID()}`;
+        const question = randomUUID();
+        const waiting = wire.expectWithin(address, deadline);
+        wire.send("end-host", "service-ask", this.key, address, question, event, payload);
+        try {
+            return await waiting;
+        }
+        finally {
+            wire.forget(address);
+        }
+    }
+}
+class ClientChannelHandle extends Events {
+    constructor(key) {
+        super(...serviceEvents(key, "channel"));
+    }
+}
+class ServerHandler extends ServerServiceBase {
+    key;
+    program;
+    endpoint = "server";
+    name;
+    channel;
+    constructor(key) {
+        super();
+        this.key = key;
+        this.program = key.program;
+        this.name = key.name;
+        this.channel = new ServerChannelHandle(key);
+        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
+    }
+    async disabled() {
+        const answer = await wire.request(["service-disabled", this.key]);
+        return answer[0];
+    }
+    async docs() {
+        const answer = await wire.request(["service-docs", this.key]);
+        return answer[0];
+    }
+}
+class ClientHandler extends ClientServiceBase {
+    key;
+    program;
+    endpoint = "client";
+    name;
+    channel;
+    constructor(key) {
+        super();
+        this.key = key;
+        this.program = key.program;
+        this.name = key.name;
+        this.channel = new ClientChannelHandle(key);
+        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
+    }
+    async disabled() {
+        const answer = await wire.request(["service-disabled", this.key]);
+        return answer[0];
+    }
+}
+export function service(key) {
+    if (!isServiceKey(key))
+        throw new Error("A complete service key is required");
+    const normalized = Object.freeze({ program: key.program, endpoint: key.endpoint, name: key.name });
+    const identity = JSON.stringify([normalized.program, normalized.endpoint, normalized.name]);
+    return handles.obtain(`service:${identity}`, () => {
+        return normalized.endpoint === "server"
+            ? new ServerHandler(normalized)
+            : new ClientHandler(normalized);
+    });
+}
+export async function enableCurrentService(definition) {
+    await wire.request(["enable-service", definition]);
+}
+export async function disableCurrentService() {
+    await wire.request(["disable-service"]);
+}
+export async function endpointService(target, endpoint) {
+    const answer = await wire.request(["endpoint-service", target, endpoint]);
+    return answer[0] ? service(answer[0]) : null;
+}
+function serviceEvents(key, scope) {
+    return [
+        (event, listener) => wire.followService(key, scope, event, listener),
+        (observer) => wire.followService(key, scope, null, (event, payload) => {
+            if (typeof event === "string")
+                observer(event, payload);
+        })
+    ];
+}
+function bindEvents(target, events) {
+    Object.assign(target, {
+        subscribe: events.subscribe.bind(events),
+        waitFor: events.waitFor.bind(events),
+        events: events.events.bind(events),
+        observe: events.observe.bind(events)
+    });
+}

package/dist/wire.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup } from "@phreshos/core";
+import type { Cleanup, ServiceKey } from "@phreshos/core";
 import Deadline from "./deadline.js";
 import type { HandleAddress } from "./domain.js";
 type Handler = (...values: unknown[]) => unknown;
@@ -30,6 +30,8 @@ declare class Wire {
     observe(target: HandleAddress | null, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     /** Follow destinationless events emitted by one Endpoint. */
     follow(target: HandleAddress | null, half: "server" | "client", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    /** Follow one exact service lifecycle or application event route. */
+    followService(key: ServiceKey, scope: "lifecycle" | "channel", event: string | null, handler: Handler): Cleanup;
     private register;
     private unregister;
     private deliver;

package/dist/wire.js

@@ -156,6 +156,16 @@ class Wire {
             this.send("end-host", "unfollow", subscription);
         });
     }
+    /** Follow one exact service lifecycle or application event route. */
+    followService(key, scope, event, handler) {
+        const subscription = randomUUID();
+        const stop = this.on("service-event", subscription, handler);
+        this.send("end-host", "service-follow", subscription, key, scope, event);
+        return once(() => {
+            stop();
+            this.send("end-host", "service-unfollow", subscription);
+        });
+    }
     register(kind, route, event, subject, impossible) {
         const subscription = randomUUID();
         if (impossible)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,10 +46,10 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.2"
+    "@phreshos/core": "^0.1.4"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.2",
+    "@phreshos/core": "^0.1.4",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }