@phpsandbox/sdk 0.1.1 → 0.1.2

package/dist/index.js

@@ -11,12 +11,15 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
 };
 var _NotebookInstance_instances, _NotebookInstance_initPromise, _NotebookInstance_init;
 import { Filesystem } from './filesystem.js';
-import Terminal from './terminal.js';
+import Terminals from './terminal.js';
 import Container from './container.js';
 import Auth from './auth.js';
 import Lsp from './lsp.js';
 import Composer from './composer.js';
-import Log from './log.js';
+import Logs from './log.js';
+import Metrics from './metrics.js';
+import Ports from './ports.js';
+import { RuntimeTelemetry } from './runtime-telemetry.js';
 import Repl from './repl.js';
 import Shell from './shell.js';
 import Services from './services.js';
@@ -32,6 +35,10 @@ export * from './types.js';
 export * from './lsp.js';
 export * from './filesystem.js';
 export * from './container.js';
+export * from './log.js';
+export * from './metrics.js';
+export * from './ports.js';
+export * from './runtime-telemetry.js';
 export * from './shell.js';
 export * from './terminal.js';
 export * from './git.js';
@@ -367,12 +374,15 @@ export class NotebookInstance {
             this.watchConnection();
             __classPrivateFieldSet(this, _NotebookInstance_initPromise, __classPrivateFieldGet(this, _NotebookInstance_instances, "m", _NotebookInstance_init).call(this), "f");
         }
-        this.file = new Filesystem(this, this.socket === null ? null : (handler) => this.onDidConnect(handler));
-        this.terminal = new Terminal(this);
+        this.files = new Filesystem(this, this.socket === null ? null : (handler) => this.onDidConnect(handler));
+        this.terminals = new Terminals(this);
         this.auth = new Auth(this);
         this.lsp = new Lsp(this);
         this.composer = new Composer(this, client);
-        this.log = new Log(this);
+        const telemetry = new RuntimeTelemetry(this);
+        this.logs = new Logs(this, telemetry);
+        this.metrics = new Metrics(this, telemetry);
+        this.ports = new Ports(this, telemetry);
         this.repl = new Repl(this);
         this.container = new Container(this);
         this.shell = new Shell(this);
@@ -421,6 +431,12 @@ export class NotebookInstance {
         }
         return this.shell.run(command, argsOrOpts);
     }
+    exec(command, argsOrOpts = [], opts) {
+        if (Array.isArray(argsOrOpts)) {
+            return this.run(command, argsOrOpts, opts).wait();
+        }
+        return this.run(command, argsOrOpts).wait();
+    }
     gitCredentials() {
         return this.client.notebook.gitCredentials(this.data.id);
     }
@@ -512,9 +528,6 @@ export class NotebookInstance {
         const socket = this.realtimeSocket();
         socket.onDidConnect(() => {
             socket.emit('okra.connected');
-            if (this.client.options.telemetry) {
-                this.container.enableTelemetry(this.client.options.telemetry);
-            }
         });
         socket.onDidClose(() => {
             socket.emit('okra.disconnected');

package/dist/log.d.ts

@@ -1,12 +1,18 @@
-import { Disposable, NotebookInstance } from './index.js';
+import type { NotebookInstance } from './index.js';
+import { RuntimeTelemetry, type RuntimeWatchOptions } from './runtime-telemetry.js';
 export interface LogEvents {
     'notebook.log': string;
 }
 export interface LogActions {
 }
-export default class Log {
+export interface RuntimeLogEntry {
+    timestamp: string;
+    source: 'runtime';
+    message: string;
+}
+export default class Logs {
     protected okra: NotebookInstance;
-    constructor(okra: NotebookInstance);
-    stream(fn: (data: string) => void): Disposable;
-    listen<T extends keyof LogEvents>(event: T, handler: (data: LogEvents[T]) => void): Disposable;
+    private readonly telemetry;
+    constructor(okra: NotebookInstance, telemetry: RuntimeTelemetry);
+    follow(options?: RuntimeWatchOptions): ReadableStream<RuntimeLogEntry>;
 }

package/dist/log.js

@@ -1,11 +1,14 @@
-export default class Log {
-    constructor(okra) {
+import { watchRuntimeTelemetry } from './runtime-telemetry.js';
+export default class Logs {
+    constructor(okra, telemetry) {
         this.okra = okra;
+        this.telemetry = telemetry;
     }
-    stream(fn) {
-        return this.okra.listen('notebook.log', fn);
-    }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
+    follow(options = {}) {
+        return watchRuntimeTelemetry(this.okra, this.telemetry, 'logs', 'notebook.log', (message) => ({
+            timestamp: new Date().toISOString(),
+            source: 'runtime',
+            message,
+        }), options);
     }
 }

package/dist/metrics.d.ts

@@ -0,0 +1,10 @@
+import type { NotebookInstance } from './index.js';
+import type { ContainerStats } from './container.js';
+import { RuntimeTelemetry, type RuntimeWatchOptions } from './runtime-telemetry.js';
+export default class Metrics {
+    private readonly okra;
+    private readonly telemetry;
+    constructor(okra: NotebookInstance, telemetry: RuntimeTelemetry);
+    current(): Promise<ContainerStats | null>;
+    watch(options?: RuntimeWatchOptions): ReadableStream<ContainerStats>;
+}

package/dist/metrics.js

@@ -0,0 +1,13 @@
+import { watchRuntimeTelemetry } from './runtime-telemetry.js';
+export default class Metrics {
+    constructor(okra, telemetry) {
+        this.okra = okra;
+        this.telemetry = telemetry;
+    }
+    current() {
+        return this.okra.invoke('container.stats');
+    }
+    watch(options = {}) {
+        return watchRuntimeTelemetry(this.okra, this.telemetry, 'stats', 'container.stats', (stats) => stats, options);
+    }
+}

package/dist/ports.d.ts

@@ -0,0 +1,10 @@
+import type { NotebookInstance } from './index.js';
+import type { PortInfo } from './container.js';
+import { RuntimeTelemetry, type RuntimeWatchOptions } from './runtime-telemetry.js';
+export default class Ports {
+    private readonly okra;
+    private readonly telemetry;
+    constructor(okra: NotebookInstance, telemetry: RuntimeTelemetry);
+    list(): Promise<PortInfo[]>;
+    watch(options?: RuntimeWatchOptions): ReadableStream<PortInfo[]>;
+}

package/dist/ports.js

@@ -0,0 +1,13 @@
+import { watchRuntimeTelemetry } from './runtime-telemetry.js';
+export default class Ports {
+    constructor(okra, telemetry) {
+        this.okra = okra;
+        this.telemetry = telemetry;
+    }
+    list() {
+        return this.okra.invoke('container.opened-ports');
+    }
+    watch(options = {}) {
+        return watchRuntimeTelemetry(this.okra, this.telemetry, 'ports', 'container.ports', (ports) => ports, options);
+    }
+}

package/dist/runtime/rest.js

@@ -12,6 +12,7 @@ const restActionRoutes = {
     'container.stop': { method: 'POST', path: '/runtime/container/stop' },
     'container.set-php': { method: 'PUT', path: '/runtime/container/php' },
     'container.opened-ports': { method: 'GET', path: '/runtime/container/ports' },
+    'container.stats': { method: 'GET', path: '/runtime/container/stats' },
     'terminal.list': { method: 'GET', path: '/runtime/terminals' },
     'shell.exec': { method: 'POST', path: '/runtime/executions' },
     'fs.info': { method: 'POST', path: '/runtime/files/info' },
@@ -37,10 +38,6 @@ const restActionRoutes = {
     'service.logs': { method: 'POST', path: '/runtime/services/logs' },
     'composer.invoke': { method: 'POST', path: '/runtime/composer/executions' },
     'composer.packages': { method: 'GET', path: '/runtime/composer/packages' },
-    'composer.dump-autoload': {
-        method: 'POST',
-        path: '/runtime/composer/autoload',
-    },
     'git.checkpoint': { method: 'POST', path: '/runtime/git/checkpoints' },
     'git.checkout': { method: 'POST', path: '/runtime/git/checkouts' },
     'git.log': { method: 'POST', path: '/runtime/git/log' },

package/dist/runtime-telemetry.d.ts

@@ -0,0 +1,15 @@
+import type { NotebookInstance } from './index.js';
+export type RuntimeTelemetryFeature = 'stats' | 'logs' | 'ports';
+export interface RuntimeWatchOptions {
+    signal?: AbortSignal;
+}
+export declare class RuntimeTelemetry {
+    private readonly okra;
+    private readonly references;
+    private synchronization;
+    constructor(okra: NotebookInstance);
+    acquire(feature: RuntimeTelemetryFeature): Promise<() => Promise<void>>;
+    private removeReference;
+    private synchronize;
+}
+export declare function watchRuntimeTelemetry<T>(okra: NotebookInstance, telemetry: RuntimeTelemetry, feature: RuntimeTelemetryFeature, event: 'container.stats' | 'container.ports' | 'notebook.log', transform: (data: any) => T, options?: RuntimeWatchOptions): ReadableStream<T>;

package/dist/runtime-telemetry.js

@@ -0,0 +1,111 @@
+export class RuntimeTelemetry {
+    constructor(okra) {
+        this.okra = okra;
+        this.references = new Map();
+        this.synchronization = Promise.resolve();
+        if (okra.runtimeTransport === 'realtime') {
+            okra.onDidConnect(() => {
+                if (this.references.size > 0) {
+                    void this.synchronize();
+                }
+            });
+        }
+    }
+    async acquire(feature) {
+        this.references.set(feature, (this.references.get(feature) ?? 0) + 1);
+        try {
+            await this.synchronize();
+        }
+        catch (error) {
+            this.removeReference(feature);
+            throw error;
+        }
+        let released = false;
+        return async () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            this.removeReference(feature);
+            await this.synchronize();
+        };
+    }
+    removeReference(feature) {
+        const references = this.references.get(feature) ?? 0;
+        if (references <= 1) {
+            this.references.delete(feature);
+        }
+        else {
+            this.references.set(feature, references - 1);
+        }
+    }
+    synchronize() {
+        this.synchronization = this.synchronization.catch(() => { }).then(async () => {
+            const features = Array.from(this.references.keys());
+            if (features.length === 0) {
+                await this.okra.invoke('container.stop-telemetry');
+            }
+            else {
+                await this.okra.invoke('container.stream-telemetry', { features });
+            }
+        });
+        return this.synchronization;
+    }
+}
+export function watchRuntimeTelemetry(okra, telemetry, feature, event, transform, options = {}) {
+    let subscription = null;
+    let release = null;
+    let closed = false;
+    let abort = null;
+    const stop = async () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        subscription?.dispose();
+        subscription = null;
+        if (abort && options.signal) {
+            options.signal.removeEventListener('abort', abort);
+        }
+        abort = null;
+        await release?.();
+        release = null;
+    };
+    return new ReadableStream({
+        start(controller) {
+            subscription = okra.listen(event, (data) => {
+                if (!closed) {
+                    controller.enqueue(transform(data));
+                }
+            });
+            if (options.signal) {
+                abort = () => {
+                    void stop().finally(() => controller.error(options.signal?.reason ?? new Error('Aborted')));
+                };
+                if (options.signal.aborted) {
+                    abort();
+                    return;
+                }
+                options.signal.addEventListener('abort', abort, { once: true });
+            }
+            void telemetry.acquire(feature).then(async (releaseTelemetry) => {
+                if (closed) {
+                    await releaseTelemetry();
+                    return;
+                }
+                release = releaseTelemetry;
+            }).catch((error) => {
+                if (!closed) {
+                    closed = true;
+                    subscription?.dispose();
+                    if (abort && options.signal) {
+                        options.signal.removeEventListener('abort', abort);
+                    }
+                    abort = null;
+                    controller.error(error);
+                }
+            });
+        },
+        cancel: stop,
+    });
+}

package/dist/schemas/publications.d.ts

@@ -64,12 +64,12 @@ export declare const PublicationProtectionModeSchema: z.ZodEnum<{
     password: "password";
 }>;
 export declare const PublicationLogStreamSchema: z.ZodEnum<{
-    build: "build";
     runtime: "runtime";
+    build: "build";
 }>;
 export declare const PublishStreamLogStreamSchema: z.ZodEnum<{
-    build: "build";
     runtime: "runtime";
+    build: "build";
     publish: "publish";
 }>;
 export declare const PublicationEventDataSchema: z.ZodObject<{
@@ -82,8 +82,8 @@ export declare const PublicationEventDataSchema: z.ZodObject<{
 export declare const PublicationLogChunkDataSchema: z.ZodObject<{
     sequence: z.ZodNumber;
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
     }>;
     content: z.ZodString;
     createdAt: z.ZodNullable<z.ZodString>;
@@ -99,8 +99,8 @@ export declare const PublishStreamPhaseSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const PublishStreamLogSchema: z.ZodObject<{
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
         publish: "publish";
     }>;
     content: z.ZodString;
@@ -135,8 +135,8 @@ export declare const PublishStreamPhaseEventSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const PublishStreamLogEventSchema: z.ZodObject<{
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
         publish: "publish";
     }>;
     content: z.ZodString;
@@ -172,8 +172,8 @@ export declare const PublishStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     type: z.ZodLiteral<"phase">;
 }, z.core.$strict>, z.ZodObject<{
     stream: z.ZodEnum<{
-        build: "build";
         runtime: "runtime";
+        build: "build";
         publish: "publish";
     }>;
     content: z.ZodString;
@@ -223,8 +223,8 @@ export declare const PublishStreamSseLogEventSchema: z.ZodObject<{
     event: z.ZodLiteral<"log">;
     data: z.ZodObject<{
         stream: z.ZodEnum<{
-            build: "build";
             runtime: "runtime";
+            build: "build";
             publish: "publish";
         }>;
         content: z.ZodString;
@@ -293,8 +293,8 @@ export declare const PublishStreamSseEventSchema: z.ZodPipe<z.ZodDiscriminatedUn
     event: z.ZodLiteral<"log">;
     data: z.ZodObject<{
         stream: z.ZodEnum<{
-            build: "build";
             runtime: "runtime";
+            build: "build";
             publish: "publish";
         }>;
         content: z.ZodString;
@@ -350,7 +350,7 @@ export declare const PublishStreamSseEventSchema: z.ZodPipe<z.ZodDiscriminatedUn
     status?: "running" | "failed" | "completed";
     data?: Record<string, unknown>;
 } | {
-    stream: "build" | "runtime" | "publish";
+    stream: "runtime" | "build" | "publish";
     content: string;
     type: "log";
 } | {
@@ -370,7 +370,7 @@ export declare const PublishStreamSseEventSchema: z.ZodPipe<z.ZodDiscriminatedUn
 } | {
     event: "log";
     data: {
-        stream: "build" | "runtime" | "publish";
+        stream: "runtime" | "build" | "publish";
         content: string;
     };
 } | {

package/dist/services.d.ts

@@ -1,4 +1,4 @@
-import { Action, Disposable, NotebookInstance } from './index.js';
+import { Action, NotebookInstance } from './index.js';
 export type NotebookServiceKind = 'app' | 'web' | 'cache' | 'task';
 export type NotebookServiceSource = 'built_in' | 'setup_task';
 export type NotebookServiceState = 'running' | 'starting' | 'stopping' | 'backoff' | 'exited' | 'fatal' | 'stopped' | 'unknown';
@@ -64,20 +64,13 @@ export interface ServiceLogOptions {
     tail?: number;
     follow?: false;
 }
-export interface ServiceLogStream {
-    id: string;
-    output: ReadableStream<string>;
-    stop(): Promise<boolean>;
-}
 export default class Services {
     protected okra: NotebookInstance;
     constructor(okra: NotebookInstance);
     list(): Promise<NotebookServiceStatus[]>;
     run(name: NotebookServiceName, command?: NotebookServiceCommand): Promise<NotebookServiceStatus>;
     stop(name: NotebookServiceName): Promise<NotebookServiceStatus>;
-    onLog(id: string, handler: (data: ServiceEvents['service.log']) => void): Disposable;
-    listen<T extends keyof ServiceEvents>(event: T, handler: (data: ServiceEvents[T]) => void): Disposable;
-    logs(name: NotebookServiceName, options: ServiceLogStreamOptions): ServiceLogStream;
+    logs(name: NotebookServiceName, options: ServiceLogStreamOptions): ReadableStream<string>;
     logs(name: NotebookServiceName, options?: ServiceLogOptions): Promise<string>;
     private followLogs;
 }

package/dist/services.js

@@ -18,12 +18,6 @@ export default class Services {
     stop(name) {
         return this.okra.invoke('service.stop', { name });
     }
-    onLog(id, handler) {
-        return this.okra.listen(`service.log.${id}`, handler);
-    }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
-    }
     logs(name, options = {}) {
         if (options.follow) {
             return this.followLogs(name, options);
@@ -80,10 +74,10 @@ export default class Services {
             close();
             return this.okra.invoke('service.stop-logs', { id });
         });
-        const output = new ReadableStream({
+        return new ReadableStream({
             start: (_controller) => {
                 controller = _controller;
-                disposables.add(this.onLog(id, (data) => {
+                disposables.add(this.okra.listen(`service.log.${id}`, (data) => {
                     controller?.enqueue(data.output);
                 }));
                 void this.okra
@@ -98,9 +92,8 @@ export default class Services {
                 });
             },
             cancel: () => {
-                void stop();
+                return stop().then(() => undefined);
             },
         });
-        return { id, output, stop };
     }
 }

package/dist/shell.d.ts

@@ -49,6 +49,15 @@ export declare class ProcessResult implements ProcessResultData {
     constructor(output: string, stdout: string, stderr: string, exitCode: number);
     throw(): this;
 }
+export declare class ProcessReadable<T> {
+    readonly stream: ReadableStream<T>;
+    private controller;
+    private closed;
+    constructor();
+    enqueue(value: T): void;
+    close(): void;
+    fail(error: unknown): void;
+}
 export declare class ShellProcess {
     readonly id: string;
     private readonly okra;

package/dist/shell.js

@@ -27,7 +27,7 @@ export class ProcessResult {
         return this;
     }
 }
-class OutputStream {
+export class ProcessReadable {
     constructor() {
         this.controller = null;
         this.closed = false;
@@ -67,9 +67,9 @@ export class ShellProcess {
     constructor(id, okra, command, opts) {
         this.id = id;
         this.okra = okra;
-        const output = new OutputStream();
-        const stdout = new OutputStream();
-        const stderr = new OutputStream();
+        const output = new ProcessReadable();
+        const stdout = new ProcessReadable();
+        const stderr = new ProcessReadable();
         this.output = output.stream;
         this.stdout = stdout.stream;
         this.stderr = stderr.stream;

package/dist/terminal.d.ts

@@ -1,4 +1,4 @@
-import { Action, Disposable, NotebookInstance } from './index.js';
+import { Action, NotebookInstance } from './index.js';
 export interface Task {
     id: string;
     command: string | string[];
@@ -14,7 +14,7 @@ export interface TerminalCreateInput {
     kind: string;
     size: [number, number];
     command?: string | string[];
-    env?: Record<string, string>;
+    env?: Record<string, string | number | boolean>;
     cwd?: string;
 }
 export interface TerminalSpawnInput {
@@ -66,7 +66,7 @@ export interface TerminalActions {
 }
 export interface SandboxProcess {
     wait(): Promise<number>;
-    input: WritableStream<string>;
+    input: WritableStream<string | Uint8Array>;
     output: ReadableStream<string>;
     kill(): Promise<boolean>;
     resize(dimensions: {
@@ -87,21 +87,27 @@ export interface SpawnOptions {
     tty?: boolean;
     abortSignal?: AbortSignal;
 }
-export default class Terminal {
+export interface TerminalOptions {
+    command?: string | string[];
+    args?: string[];
+    kind?: string;
+    size?: [number, number];
+    cwd?: string;
+    env?: Record<string, string | number | boolean>;
+    id?: string;
+    osc?: boolean;
+    tty?: boolean;
+    abortSignal?: AbortSignal;
+}
+export default class Terminals {
     protected okra: NotebookInstance;
     constructor(okra: NotebookInstance);
     list(): Promise<Task[]>;
-    create(input: TerminalCreateInput): Promise<Task>;
-    onStarted(handler: (t: Task) => void): Disposable;
-    resize(id: string, size: [number, number]): Promise<boolean>;
-    onOutput(id: string, handler: (data: TerminalEvents['terminal.output']) => void): Disposable;
-    input(id: string, input: string): Promise<boolean>;
-    listen<T extends keyof TerminalEvents>(event: T, handler: (data: TerminalEvents[T]) => void): Disposable;
+    create(options?: TerminalOptions): Promise<SandboxProcess & Task>;
     attach(id: string, opts?: {
         replayHistory?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<(SandboxProcess & Task) | false>;
-    spawn(command: string, args: string[], opts?: SpawnOptions): Promise<SandboxProcess & Task>;
     private processHandle;
 }
 export {};