@phpsandbox/sdk 0.1.1 → 0.1.4

package/dist/filesystem.js

@@ -1,3 +1,4 @@
+import { UnsupportedRuntimeTransportError } from './errors/index.js';
 import { ErrorEvent } from './types.js';
 import { nanoid } from 'nanoid';
 export var FileType;
@@ -84,28 +85,195 @@ export class Filesystem {
             }
         });
     }
-    info(path) {
-        return this.okra.invoke('fs.info', { path });
+    async write(path, contents, options = {}) {
+        const resolvedOptions = {
+            overwrite: true,
+            create: true,
+            unlock: false,
+            atomic: false,
+            ...options,
+        };
+        const source = typeof contents === 'string' ? new TextEncoder().encode(contents) : contents;
+        if (this.okra.runtimeTransport === 'rest') {
+            const bytes = source instanceof Uint8Array ? source : await collectBytes(source);
+            await this.okra.invoke('fs.writeFile', {
+                path,
+                contents: bytes,
+                options: resolvedOptions,
+            }).catch((error) => this.handleError(error));
+            return;
+        }
+        const id = nanoid();
+        const completion = this.okra.invoke('fs.writeStream', { id, path, options: resolvedOptions });
+        void completion.catch(() => { });
+        try {
+            for await (const chunk of toAsyncIterable(source)) {
+                const written = await this.okra.invoke('fs.writeChunk', { id, contents: chunk });
+                if (!written) {
+                    throw new Error(`File write stream ${id} is not available`);
+                }
+            }
+            const ended = await this.okra.invoke('fs.endWrite', { id });
+            if (!ended) {
+                throw new Error(`File write stream ${id} could not be completed`);
+            }
+            await completion;
+        }
+        catch (error) {
+            await this.okra.invoke('fs.abortWrite', { id }).catch(() => false);
+            await completion.catch(() => false);
+            throw error;
+        }
+    }
+    async read(path) {
+        try {
+            const content = await this.okra.invoke('fs.readFile', { path });
+            return content instanceof Uint8Array ? content : new TextEncoder().encode(content);
+        }
+        catch (error) {
+            this.handleError(error);
+        }
     }
-    async write(path, contents, options = { overwrite: true, create: true, unlock: false, atomic: false }) {
-        if (typeof contents === 'string') {
-            return this.okra.invoke('fs.write', { path, contents });
+    async readText(path) {
+        return new TextDecoder().decode(await this.read(path));
+    }
+    async readLines(path, range) {
+        try {
+            const result = await this.okra.invoke('fs.readFile', {
+                path,
+                lineRange: {
+                    lineStart: range.start,
+                    lineEnd: range.end,
+                },
+            });
+            if (typeof result === 'string' || result instanceof Uint8Array) {
+                throw new Error(`Unexpected ranged file response for ${path}`);
+            }
+            return {
+                start: result.lineStart,
+                end: result.lineEnd,
+                content: result.content,
+                ...(result.error === null ? {} : { warning: result.error }),
+            };
+        }
+        catch (error) {
+            this.handleError(error);
         }
-        const bytes = contents instanceof Uint8Array ? contents : await collectBytes(contents);
-        await this.writeFile(path, bytes, options);
-        return true;
     }
-    read(path) {
+    readStream(path) {
+        if (this.okra.runtimeTransport === 'rest') {
+            return new ReadableStream({
+                start: async (controller) => {
+                    try {
+                        controller.enqueue(await this.read(path));
+                        controller.close();
+                    }
+                    catch (error) {
+                        controller.error(error);
+                    }
+                },
+            });
+        }
+        const id = nanoid();
+        let disposable = null;
+        let closed = false;
         return new ReadableStream({
-            start: async (controller) => {
-                try {
-                    controller.enqueue(await this.readFile(path));
-                    controller.close();
+            start: (controller) => {
+                disposable = this.okra.listen(`fs.read.${id}`, (event) => {
+                    controller.enqueue(event.data);
+                });
+                void this.okra.invoke('fs.readStream', { id, path }).then(() => {
+                    if (!closed) {
+                        closed = true;
+                        disposable?.dispose();
+                        controller.close();
+                    }
+                }).catch((error) => {
+                    if (!closed) {
+                        closed = true;
+                        disposable?.dispose();
+                        controller.error(error);
+                    }
+                });
+            },
+            cancel: async () => {
+                if (!closed) {
+                    closed = true;
+                    disposable?.dispose();
+                    await this.okra.invoke('fs.cancelRead', { id }).catch(() => false);
                 }
-                catch (error) {
-                    controller.error(error);
+            },
+        });
+    }
+    follow(path, options = {}) {
+        if (this.okra.runtimeTransport === 'rest') {
+            return new ReadableStream({
+                start(controller) {
+                    controller.error(new UnsupportedRuntimeTransportError('Following files requires the realtime transport.'));
+                },
+            });
+        }
+        const id = nanoid();
+        let disposable = null;
+        let abort = null;
+        let started = false;
+        let closed = false;
+        const stop = async () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            disposable?.dispose();
+            disposable = null;
+            if (abort && options.signal) {
+                options.signal.removeEventListener('abort', abort);
+            }
+            abort = null;
+            if (started) {
+                await this.okra.invoke('fs.cancelFollow', { id }).catch(() => false);
+            }
+        };
+        return new ReadableStream({
+            start: (controller) => {
+                disposable = this.okra.listen(`fs.follow.${id}`, (event) => {
+                    if (!closed) {
+                        controller.enqueue(event.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 });
                 }
+                started = true;
+                void this.okra.invoke('fs.follow', { id, path, lines: options.lines ?? 10 }).then(() => {
+                    if (!closed) {
+                        closed = true;
+                        disposable?.dispose();
+                        if (abort && options.signal) {
+                            options.signal.removeEventListener('abort', abort);
+                        }
+                        abort = null;
+                        controller.close();
+                    }
+                }).catch((error) => {
+                    if (!closed) {
+                        closed = true;
+                        disposable?.dispose();
+                        if (abort && options.signal) {
+                            options.signal.removeEventListener('abort', abort);
+                        }
+                        abort = null;
+                        controller.error(error);
+                    }
+                });
             },
+            cancel: stop,
         });
     }
     find(query, options = {
@@ -187,56 +355,38 @@ export class Filesystem {
             .invoke('fs.textSearch', { query, options: { ...defaultOptions, ...options } })
             .finally(() => disposable.dispose());
     }
-    mkdir(path) {
-        return this.okra.invoke('fs.mkdir', { path });
-    }
-    move(from, to) {
-        return this.okra.invoke('fs.move', { from, to });
-    }
-    remove(path, type) {
-        return this.okra.invoke('fs.remove', { path, type });
-    }
-    async readFile(path, lineRange) {
-        try {
-            const content = await this.okra.invoke('fs.readFile', { path, lineRange });
-            if (content instanceof Uint8Array) {
-                return content;
-            }
-            if (typeof content === 'string') {
-                return new TextEncoder().encode(content);
-            }
-            return content;
-        }
-        catch (e) {
-            this.handleError(e);
-        }
-    }
-    tail(path, lines = 10) {
-        return this.okra.invoke('fs.tail', { path, lines }).catch((e) => this.handleError(e));
-    }
-    writeFile(path, contents, options) {
-        return this.okra
-            .invoke('fs.writeFile', {
-            path,
-            contents,
-            options,
-        })
-            .catch((e) => this.handleError(e));
+    tail(path, options = {}) {
+        return this.okra.invoke('fs.tail', { path, lines: options.lines ?? 10 }).catch((e) => this.handleError(e));
     }
     stat(path) {
         return this.okra.invoke('fs.stat', { path }).catch((e) => this.handleError(e));
     }
-    rename(from, to, options) {
-        return this.okra.invoke('fs.rename', { from, to, options }).catch((e) => this.handleError(e));
+    move(from, to, options = {}) {
+        return this.okra.invoke('fs.rename', {
+            from,
+            to,
+            options: { overwrite: false, ...options },
+        }).catch((e) => this.handleError(e));
     }
-    delete(path, options) {
-        return this.okra.invoke('fs.delete', { path, options }).catch((e) => this.handleError(e));
+    remove(path, options = {}) {
+        return this.okra.invoke('fs.delete', {
+            path,
+            options: { recursive: false, useTrash: false, atomic: false, ...options },
+        }).catch((e) => this.handleError(e));
     }
-    copy(source, destination, options) {
-        return this.okra.invoke('fs.copy', { source, destination, options }).catch((e) => this.handleError(e));
+    copy(source, destination, options = {}) {
+        return this.okra.invoke('fs.copy', {
+            source,
+            destination,
+            options: { overwrite: false, ...options },
+        }).catch((e) => this.handleError(e));
     }
-    readDirectory(path, include = [], exclude = []) {
-        return this.okra.invoke('fs.readDirectory', { path, include, exclude }).catch((e) => this.handleError(e));
+    list(path, options = {}) {
+        return this.okra.invoke('fs.readDirectory', {
+            path,
+            include: options.include ?? [],
+            exclude: options.exclude ?? [],
+        }).catch((e) => this.handleError(e));
     }
     createDirectory(path) {
         return this.okra.invoke('fs.createDirectory', { path }).catch((e) => this.handleError(e));
@@ -269,17 +419,17 @@ export class Filesystem {
             .then(() => true)
             .catch(() => false);
     }
-    async download(chunk, exclude, include) {
+    async download(options = {}) {
         const id = nanoid();
-        const stream = !!chunk;
+        const stream = !!options.onChunk;
         const chunks = [];
         const disposable = this.okra.listen(`fs.download.${id}`, stream
-            ? chunk
+            ? options.onChunk
             : (data) => {
                 chunks.push(data);
             });
         return this.okra
-            .invoke('fs.download', { id, exclude, include })
+            .invoke('fs.download', { id, exclude: options.exclude, include: options.include })
             .then(() => new Blob(chunks, { type: 'application/octet-stream' }))
             .finally(() => disposable.dispose());
     }
@@ -293,6 +443,13 @@ export class Filesystem {
         throw e;
     }
 }
+async function* toAsyncIterable(contents) {
+    if (contents instanceof Uint8Array) {
+        yield contents;
+        return;
+    }
+    yield* contents;
+}
 async function collectBytes(stream) {
     const chunks = [];
     let length = 0;

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 import { Filesystem, FilesystemActions, FilesystemEvents } from './filesystem.js';
-import Terminal, { TerminalEvents, TerminalActions, type SpawnOptions } from './terminal.js';
-import Container, { ContainerActions, ContainerEvents, PortInfo, TelemetryFeature } from './container.js';
+import Terminals, { TerminalEvents, TerminalActions, type SpawnOptions } from './terminal.js';
+import Container, { ContainerActions, ContainerEvents, PortInfo } from './container.js';
 import Auth, { AuthActions } from './auth.js';
 import Lsp, { LspActions, LspEvents } from './lsp.js';
 import Composer, { ComposerActions, ComposerEvents } from './composer.js';
-import Log, { LogActions, LogEvents } from './log.js';
+import Logs, { LogActions, LogEvents } from './log.js';
+import Metrics from './metrics.js';
+import Ports from './ports.js';
 import Repl, { ReplActions, ReplEvents } from './repl.js';
-import Shell, { ShellEvents, ShellActions, type ShellProcess } from './shell.js';
+import { ShellEvents, ShellActions, type ProcessResult, type ShellProcess } from './shell.js';
 import Services, { ServiceActions, ServiceEvents } from './services.js';
 import Config, { ConfigActions } from './config.js';
 import { EventDispatcher } from './events/index.js';
@@ -19,6 +21,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';
@@ -299,7 +305,6 @@ export declare class NotebookApi {
 export interface PHPSandboxClientOptions {
     debug?: boolean;
     startClosed?: boolean;
-    telemetry?: Set<TelemetryFeature>;
     fetch?: typeof globalThis.fetch;
     webSocket?: unknown;
     runtimeUrlProvider?: (notebookId: string) => Promise<string>;
@@ -384,15 +389,17 @@ export declare class NotebookInstance {
     #private;
     readonly data: NotebookData;
     protected client: Client;
-    readonly file: Filesystem;
-    readonly terminal: Terminal;
+    readonly files: Filesystem;
+    readonly terminals: Terminals;
     readonly auth: Auth;
     readonly lsp: Lsp;
     readonly composer: Composer;
-    readonly log: Log;
+    readonly logs: Logs;
+    readonly metrics: Metrics;
+    readonly ports: Ports;
     readonly repl: Repl;
     readonly container: Container;
-    readonly shell: Shell;
+    private readonly shell;
     readonly git: Git;
     readonly services: Services;
     readonly config: Config;
@@ -412,6 +419,8 @@ export declare class NotebookInstance {
     publish(input: PublishInput): Promise<PublicationRun>;
     run(command: string | string[], opts?: SpawnOptions): ShellProcess;
     run(command: string, args: string[], opts?: SpawnOptions): ShellProcess;
+    exec(command: string | string[], opts?: SpawnOptions): Promise<ProcessResult>;
+    exec(command: string, args: string[], opts?: SpawnOptions): Promise<ProcessResult>;
     gitCredentials(): Promise<GitCredentials>;
     destroy(): Promise<void>;
     stop(): Promise<void>;

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>;