@phreshos/server 0.1.18 → 0.1.20

package/README.md

@@ -19,7 +19,7 @@ capabilities, or contain System and transport implementations.
 
 Its `System` contract exposes the complete unresolved Appearance with
 replacement authority, authoritative Program and Process discovery, runtime
-Program creation, lifecycle events, and publicly served values.
+Program creation, lifecycle events, and flat public uploads.
 `system.appearance.snapshot()` explicitly reads current authoritative state;
 `subscribe("change", listener)` receives only replacements published after
 registration, and `update()` validates and persists a complete replacement.
@@ -27,16 +27,19 @@ Wallpaper filenames are ordinary Appearance values rather than separate SDK
 capabilities:
 
 ```ts
-const served = await system.serve(file)
+const upload = await system.uploads.write(file)
+const bytes = await system.uploads.bytes(upload.file)
 const appearance = await system.appearance.snapshot()
 
 await system.appearance.update({
   ...appearance,
   desktopWallpaper: {
     ...appearance.desktopWallpaper,
-    light: served.file
+    light: upload.file
   }
 })
+
+void bytes
 ```
 
 Its JavaScript entry point adapts the Process IPC boundary to these contracts.

package/dist/channel.d.ts

@@ -1,9 +1,15 @@
-import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
+import type { Channel as CoreChannel, ChannelCapture as CoreChannelCapture, ChannelEvents as CoreChannelEvents, ChannelMessage as CoreChannelMessage, Cleanup } from "@phreshos/core";
 import { type Endpoint } from "./domain.js";
+/** One value addressed to the current Server, with a server-visible sender. */
+export type ChannelMessage<Payload = unknown> = CoreChannelMessage<Payload, Endpoint | null>;
 /** Handles one question addressed to the current Server. */
 export type Answerer<Payload = unknown, Result = undefined> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
+/** Applies the server-visible sender envelope to known Channel events. */
+export type ChannelEvents<Events extends object> = CoreChannelEvents<Events, Endpoint | null>;
+/** Every event observable through the current Server's Channel. */
+export type ChannelCapture<Events extends object = {}> = CoreChannelCapture<Events, Endpoint | null>;
 /** Events and questions explicitly accepted by the current Server. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint> {
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
     /** Registers one answerer; omitting its return produces `undefined`. */
     answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
 }

package/dist/channel.js

@@ -20,6 +20,6 @@ class ServerChannel extends Events {
 }
 function message(value) {
     const raw = value;
-    return { from: endpoint(raw.from), payload: raw.payload };
+    return { from: raw.from ? endpoint(raw.from) : null, payload: raw.payload };
 }
 export const channel = new ServerChannel();

package/dist/main.d.ts

@@ -1,9 +1,9 @@
 export { system, type System, type SystemProcess, type SystemProgram, type ClientDescription, type SystemProcessEvents, type SystemProcessExit, type SystemProgramEvents, type SystemProgramUninstall, type ProgramDescription, type ServerDescription } from "./system.js";
 export { current, type Current, type CurrentClient } from "./current.js";
-export { type Answerer, type Channel } from "./channel.js";
+export { type Answerer, type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
 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, 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, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, ThemedValue, WritableAppearance, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";
+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, 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.d.ts

@@ -1,4 +1,4 @@
-import type { Exit, Layer, Position, ServedFile, ServiceKey, Size, Subscribable, WritableAppearance } from "@phreshos/core";
+import type { Exit, Layer, Position, ServiceKey, Size, Subscribable, SystemUploads, WritableAppearance } from "@phreshos/core";
 import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 import { type Storage } from "./storage.js";
@@ -111,6 +111,8 @@ export interface System {
     readonly appearance: WritableAppearance;
     readonly program: SystemProgram;
     readonly process: SystemProcess;
+    /** Flat System-owned public uploads capability. */
+    readonly uploads: SystemUploads;
     /** Returns a stable handle for one exact Service identity. */
     service<ServiceEvents extends object = {}>(key: ServiceKey & {
         endpoint: "server";
@@ -118,8 +120,6 @@ export interface System {
     service<ServiceEvents extends object = {}>(key: ServiceKey & {
         endpoint: "client";
     }): ClientServiceHandler<ServiceEvents>;
-    /** Publishes a value through the system and returns its public file metadata. */
-    serve(value: unknown): Promise<ServedFile>;
 }
 /** Authoritative system capabilities for the currently executing Server. */
 export declare const system: System;

package/dist/system.js

@@ -1,6 +1,6 @@
 import Events from "./events.js";
 import { exit, lifecycleEndpoint, process, program } from "./domain.js";
-import serve from "./served.js";
+import { uploads } from "./uploads.js";
 import ServerAppearance from "./appearance.js";
 import wire from "./wire.js";
 import { prepareService } from "./service.js";
@@ -10,8 +10,8 @@ class ServerSystem {
     appearance = new ServerAppearance();
     program = new ServerSystemProgram();
     process = new ServerSystemProcess();
+    uploads = uploads;
     service(key) { return prepareService(key); }
-    serve(value) { return serve(value); }
 }
 class ServerSystemProgram extends Events {
     constructor() {

package/dist/uploads.d.ts

@@ -0,0 +1,14 @@
+import { type SystemUploads, type Upload } from "@phreshos/core";
+/** Flat upload access performed locally by a Server Endpoint. */
+declare class ServerUploads implements SystemUploads {
+    private accessPromise;
+    write(value: unknown): Promise<Upload>;
+    stream(file: string): Promise<ReadableStream<Uint8Array>>;
+    bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;
+    text(file: string): Promise<string>;
+    json<Value>(file: string): Promise<Value>;
+    stat(file: string): Promise<Upload | null>;
+    private access;
+}
+export declare const uploads: ServerUploads;
+export {};

package/dist/uploads.js

@@ -0,0 +1,84 @@
+import { isUploadFile } from "@phreshos/core";
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, mkdirSync } from "node:fs";
+import { rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { content } from "./storage.js";
+import wire from "./wire.js";
+/** Flat upload access performed locally by a Server Endpoint. */
+class ServerUploads {
+    accessPromise = null;
+    async write(value) {
+        const access = await this.access();
+        const source = content(value);
+        const identity = randomUUID();
+        const file = `${identity}.${source.extension}`;
+        const temporary = join(access.root, `.${identity}.uploading`);
+        const destination = join(access.root, file);
+        let size = 0;
+        mkdirSync(access.root, { recursive: true });
+        try {
+            await pipeline(Readable.fromWeb(source.stream), async function* (chunks) {
+                for await (const chunk of chunks) {
+                    size += chunk.byteLength;
+                    if (size > access.limit)
+                        throw new Error(`The upload exceeds ${access.limit / 1024 / 1024 / 1024} GB`);
+                    yield chunk;
+                }
+            }, createWriteStream(temporary, { flags: "wx" }));
+            await rename(temporary, destination);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+        const upload = await this.stat(file);
+        if (!upload)
+            throw new Error("The completed upload could not be described");
+        return upload;
+    }
+    async stream(file) {
+        requireFile(file);
+        const { root } = await this.access();
+        return Readable.toWeb(createReadStream(join(root, file)));
+    }
+    async bytes(file) {
+        return new Uint8Array(await new Response(await this.stream(file)).arrayBuffer());
+    }
+    async text(file) {
+        return new Response(await this.stream(file)).text();
+    }
+    async json(file) {
+        return JSON.parse(await this.text(file));
+    }
+    async stat(file) {
+        requireFile(file);
+        const answer = await wire.request(["uploads", "stat", file]);
+        return answer[0];
+    }
+    access() {
+        if (!this.accessPromise) {
+            const resolving = wire.request(["uploads", "access"]).then(answer => {
+                const [root, limit] = answer;
+                if (typeof root !== "string" || !root || typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) {
+                    throw new Error("The System returned invalid upload access");
+                }
+                return { root, limit };
+            });
+            const retained = resolving.catch(error => {
+                if (this.accessPromise === retained)
+                    this.accessPromise = null;
+                throw error;
+            });
+            this.accessPromise = retained;
+        }
+        return this.accessPromise;
+    }
+}
+function requireFile(file) {
+    if (!isUploadFile(file))
+        throw new Error("That is not an upload file");
+}
+export const uploads = new ServerUploads();

package/package.json

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

package/dist/served.d.ts

@@ -1,3 +0,0 @@
-import type { ServedFile } from "@phreshos/core";
-/** Writes one public value directly into the system-managed served-file area. */
-export default function serve(value: unknown): Promise<ServedFile>;

package/dist/served.js

@@ -1,41 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { createWriteStream, mkdirSync, statSync } from "node:fs";
-import { rename, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { content } from "./storage.js";
-import wire from "./wire.js";
-/** Writes one public value directly into the system-managed served-file area. */
-export default async function serve(value) {
-    const answer = await wire.request(["serve"]);
-    const [root, limit] = answer;
-    const source = content(value);
-    const identity = randomUUID();
-    const file = `${identity}.${source.extension}`;
-    const temporary = join(root, `.${identity}.serving`);
-    const destination = join(root, file);
-    let size = 0;
-    mkdirSync(root, { recursive: true });
-    try {
-        await pipeline(Readable.fromWeb(source.stream), async function* (chunks) {
-            for await (const chunk of chunks) {
-                size += chunk.byteLength;
-                if (size > limit)
-                    throw new Error(`The served value exceeds ${limit / 1024 / 1024 / 1024} GB`);
-                yield chunk;
-            }
-        }, createWriteStream(temporary, { flags: "wx" }));
-        await rename(temporary, destination);
-    }
-    catch (error) {
-        await rm(temporary, { force: true }).catch(() => undefined);
-        throw error;
-    }
-    return {
-        file,
-        type: source.type,
-        size,
-        time: Math.round(statSync(destination).mtimeMs)
-    };
-}