@phpsandbox/sdk 0.0.68 → 0.1.2

package/dist/composer.d.ts

@@ -1,11 +1,16 @@
-import { Action, Client, ComposerCredentials, Disposable, NotebookInstance } from './index.js';
-export interface ComposerEvents {
-    'composer.log': string;
-}
-export interface Result {
-    exitCode: number;
-    output: string;
+import { ComposerCredentials, type Action, type Client, type NotebookInstance } from './index.js';
+import { ProcessResult, type ProcessOutputChunk, type ProcessOutputSource, type ProcessResultData } from './shell.js';
+export interface ComposerEventData {
+    'composer.output': {
+        id: string;
+        output: string;
+        source: ProcessOutputSource;
+    };
 }
+type ComposerEventPattern = `${keyof ComposerEventData}.${string}`;
+export type ComposerEvents = ComposerEventData & {
+    [K in ComposerEventPattern]: ComposerEventData['composer.output'];
+};
 export interface ComposerPackage {
     name: string;
     _installedVersion: string;
@@ -14,32 +19,40 @@ export interface ComposerPackage {
 }
 export interface ComposerActions {
     'composer.invoke': Action<{
+        id: string;
         command: ComposerCommand;
         args: Argument;
         options: Options;
-    }, Result>;
-    'composer.dump-autoload': Action<undefined, {
-        message: string;
-        success: boolean;
-    }>;
+    }, ProcessResultData>;
+    'composer.kill': Action<{
+        id: string;
+    }, boolean>;
     'composer.packages': Action<undefined, ComposerPackage[]>;
 }
-export type ComposerCommand = 'install' | 'update' | 'require' | 'remove' | 'search' | 'show';
+export type ComposerCommand = 'install' | 'update' | 'require' | 'remove' | 'search' | 'show' | 'dump-autoload';
 export type Argument<Name extends string = string, Type extends string | string[] = string | string[]> = Record<Name, Type>;
 export type Options<Name extends string = string, Type extends string | string[] | boolean = string | string[] | boolean> = Record<Name, Type>;
+export declare class ComposerProcess {
+    readonly id: string;
+    private readonly okra;
+    readonly output: ReadableStream<ProcessOutputChunk>;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    private readonly completion;
+    constructor(id: string, okra: NotebookInstance, command: ComposerCommand, args: Argument, options: Options);
+    wait(): Promise<ProcessResult>;
+    kill(): Promise<void>;
+}
 export default class Composer {
     protected okra: NotebookInstance;
     readonly credentials: ComposerCredentials;
     constructor(okra: NotebookInstance, client: Client);
-    invoke(command: ComposerCommand, args?: Argument, options?: Options): Promise<Result>;
-    dumpAutoload(): Promise<{
-        message: string;
-        success: boolean;
-    }>;
-    install(options?: Options): Promise<Result>;
-    update(args: Argument<'packages'>, options?: Options): Promise<Result>;
-    require(packages: Argument<'packages'>, options?: Options): Promise<Result>;
-    remove(args: Argument<'packages'>, options?: Options): Promise<Result>;
-    stream(fn: (data: string) => void): Disposable;
+    run(command: ComposerCommand, args?: Argument, options?: Options): ComposerProcess;
+    dumpAutoload(options?: Options): ComposerProcess;
+    install(options?: Options): ComposerProcess;
+    update(args: Argument<'packages'>, options?: Options): ComposerProcess;
+    require(packages: Argument<'packages'>, options?: Options): ComposerProcess;
+    remove(args: Argument<'packages'>, options?: Options): ComposerProcess;
     packages(): Promise<ComposerPackage[]>;
 }
+export {};

package/dist/composer.js

@@ -1,29 +1,79 @@
 import { ComposerCredentials } from './index.js';
+import { ProcessReadable, ProcessResult, } from './shell.js';
+import { nanoid } from 'nanoid';
+export class ComposerProcess {
+    constructor(id, okra, command, args, options) {
+        this.id = id;
+        this.okra = okra;
+        const output = new ProcessReadable();
+        const stdout = new ProcessReadable();
+        const stderr = new ProcessReadable();
+        this.output = output.stream;
+        this.stdout = stdout.stream;
+        this.stderr = stderr.stream;
+        const encoder = new TextEncoder();
+        let subscription = this.okra.listen(`composer.output.${this.id}`, (event) => {
+            const data = encoder.encode(event.output);
+            const source = event.source ?? 'output';
+            output.enqueue({ source, data });
+            if (source === 'stderr') {
+                stderr.enqueue(data);
+            }
+            else {
+                stdout.enqueue(data);
+            }
+        });
+        const finish = () => {
+            subscription?.dispose();
+            subscription = null;
+            output.close();
+            stdout.close();
+            stderr.close();
+        };
+        const fail = (error) => {
+            subscription?.dispose();
+            subscription = null;
+            output.fail(error);
+            stdout.fail(error);
+            stderr.fail(error);
+        };
+        this.completion = this.okra.invoke('composer.invoke', { id, command, args, options }).then((result) => {
+            finish();
+            return new ProcessResult(result.output, result.stdout, result.stderr, result.exitCode);
+        }).catch((error) => {
+            fail(error);
+            throw error;
+        });
+    }
+    wait() {
+        return this.completion;
+    }
+    async kill() {
+        await this.okra.invoke('composer.kill', { id: this.id });
+    }
+}
 export default class Composer {
     constructor(okra, client) {
         this.okra = okra;
         this.credentials = new ComposerCredentials(client, okra.data.id);
     }
-    invoke(command, args = {}, options = {}) {
-        return this.okra.invoke('composer.invoke', { command, args, options });
+    run(command, args = {}, options = {}) {
+        return new ComposerProcess(nanoid(), this.okra, command, args, options);
     }
-    dumpAutoload() {
-        return this.okra.invoke('composer.dump-autoload');
+    dumpAutoload(options = {}) {
+        return this.run('dump-autoload', {}, options);
     }
     install(options = {}) {
-        return this.invoke('install', {}, options);
+        return this.run('install', {}, options);
     }
     update(args, options = {}) {
-        return this.invoke('update', args, options);
+        return this.run('update', args, options);
     }
     require(packages, options = {}) {
-        return this.invoke('require', packages, options);
+        return this.run('require', packages, options);
     }
     remove(args, options = {}) {
-        return this.invoke('remove', args, options);
-    }
-    stream(fn) {
-        return this.okra.listen('composer.log', fn);
+        return this.run('remove', args, options);
     }
     packages() {
         return this.okra.invoke('composer.packages');

package/dist/container.d.ts

@@ -1,4 +1,4 @@
-import { Action, Disposable, NotebookInstance } from './index.js';
+import { Action, NotebookInstance } from './index.js';
 interface Stat {
     usage: number;
     limit: number;
@@ -38,6 +38,7 @@ export interface ContainerActions {
         state: NotebookState;
     }>;
     'container.opened-ports': Action<{}, PortInfo[]>;
+    'container.stats': Action<{}, ContainerStats | null>;
     'container.set-php': Action<{
         version: string;
     }, {
@@ -57,13 +58,8 @@ export default class Container {
     state(): Promise<{
         state: NotebookState;
     }>;
-    openedPorts(): Promise<PortInfo[]>;
     setPhp(version: string): Promise<{
         version: string;
     }>;
-    enableTelemetry(features: Set<TelemetryFeature>): Promise<void>;
-    stopTelemetry(): Promise<void>;
-    listen<T extends keyof ContainerEvents>(event: T, handler: (data: ContainerEvents[T]) => void): Disposable;
-    onPort(handler: (port: PortInfo, type: 'open' | 'close') => void): Disposable;
 }
 export {};

package/dist/container.js

@@ -24,35 +24,7 @@ export default class Container {
     state() {
         return this.okra.invoke('container.state');
     }
-    openedPorts() {
-        return this.okra.invoke('container.opened-ports');
-    }
     setPhp(version) {
         return this.okra.invoke('container.set-php', { version });
     }
-    enableTelemetry(features) {
-        return this.okra.invoke('container.stream-telemetry', { features: Array.from(features) });
-    }
-    stopTelemetry() {
-        return this.okra.invoke('container.stop-telemetry');
-    }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
-    }
-    onPort(handler) {
-        let ports = [];
-        return this.listen('container.ports', (newPorts) => {
-            for (const port of newPorts) {
-                if (!ports.some((p) => p.port === port.port)) {
-                    handler(port, 'open');
-                }
-            }
-            for (const port of ports) {
-                if (!newPorts.some((p) => p.port === port.port)) {
-                    handler(port, 'close');
-                }
-            }
-            ports = newPorts;
-        });
-    }
 }

package/dist/filesystem.d.ts

@@ -60,6 +60,27 @@ export interface FileDeleteOptions {
         postfix: string;
     };
 }
+export type FileContents = string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+export interface FileListOptions {
+    include?: string[];
+    exclude?: string[];
+}
+export interface FileTailOptions {
+    lines?: number;
+}
+export interface FileLineRange {
+    start: number;
+    end: number;
+}
+export interface FileLineRangeResult extends FileLineRange {
+    content: string;
+    warning?: string;
+}
+export interface FileDownloadOptions {
+    onChunk?: (data: Uint8Array) => void;
+    exclude?: string[];
+    include?: string[];
+}
 export interface SearchOptions {
     /**
      * The maximum number of results to be returned.
@@ -375,6 +396,28 @@ export interface FilesystemActions {
         contents: Uint8Array;
         options: FileWriteOptions;
     }, void>;
+    'fs.readStream': Action<{
+        id: string;
+        path: string;
+    }, boolean>;
+    'fs.cancelRead': Action<{
+        id: string;
+    }, boolean>;
+    'fs.writeStream': Action<{
+        id: string;
+        path: string;
+        options: FileWriteOptions;
+    }, boolean>;
+    'fs.writeChunk': Action<{
+        id: string;
+        contents: Uint8Array;
+    }, boolean>;
+    'fs.endWrite': Action<{
+        id: string;
+    }, boolean>;
+    'fs.abortWrite': Action<{
+        id: string;
+    }, boolean>;
     'fs.stat': Action<{
         path: string;
     }, Stats>;
@@ -424,6 +467,10 @@ interface FilesystemEventData {
     'fs.watch': FileChange;
     'fs.download': Uint8Array;
     'fs.text.search': TextSearchResult | false;
+    'fs.read': {
+        id: string;
+        data: Uint8Array;
+    };
 }
 type PrefixKey<K extends keyof FilesystemEventData> = `${K}.${string}`;
 export type FilesystemEvents = FilesystemEventData & {
@@ -453,29 +500,23 @@ export declare class Filesystem {
     private watches;
     constructor(okra: NotebookInstance, registerReconnect?: ((handler: () => void) => Disposable) | null);
     private registerReconnectHandler;
-    info(path: string): Promise<FileInfo>;
-    write(path: string, contents: string): Promise<boolean>;
+    write(path: string, contents: FileContents, options?: Partial<FileWriteOptions>): Promise<void>;
+    read(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    readLines(path: string, range: FileLineRange): Promise<FileLineRangeResult>;
+    readStream(path: string): ReadableStream<Uint8Array>;
     find(query: string, options?: Partial<FileSearchOptions>): Promise<FileResult[]>;
     search(query: TextSearchQuery, options?: Partial<TextSearchOptions>, onMatch?: (result: TextSearchResult | false) => boolean | Promise<boolean> | void | Promise<void>): Promise<[boolean, TextSearchMatch[]]>;
-    mkdir(path: string): Promise<boolean>;
-    move(from: string, to: string): Promise<boolean>;
-    remove(path: string, type: 'file' | 'directory'): Promise<boolean>;
-    readFile(path: string): Promise<Uint8Array>;
-    readFile(path: string, lineRange: {
-        lineStart: number;
-        lineEnd: number;
-    }): Promise<ReadFileRangeResult>;
-    tail(path: string, lines?: number): Promise<string>;
-    writeFile(path: string, contents: Uint8Array, options: FileWriteOptions): Promise<void>;
+    tail(path: string, options?: FileTailOptions): Promise<string>;
     stat(path: string): Promise<Stats>;
-    rename(from: string, to: string, options: FileOverwriteOptions): Promise<void>;
-    delete(path: string, options: FileDeleteOptions): Promise<void>;
-    copy(source: string, destination: string, options: FileOverwriteOptions): Promise<void>;
-    readDirectory(path: string, include?: string[], exclude?: string[]): Promise<[string, FileType, number | null][]>;
+    move(from: string, to: string, options?: Partial<FileOverwriteOptions>): Promise<void>;
+    remove(path: string, options?: Partial<FileDeleteOptions>): Promise<void>;
+    copy(source: string, destination: string, options?: Partial<FileOverwriteOptions>): Promise<void>;
+    list(path: string, options?: FileListOptions): Promise<[string, FileType, number | null][]>;
     createDirectory(path: string): Promise<void>;
     watch(path: string, options: WatchOptions, onDidChange: (e: FileChange) => void): Promise<FilesystemSubscription>;
     exists(path: string): Promise<boolean>;
-    download(chunk?: (data: Uint8Array) => void, exclude?: string[], include?: string[]): Promise<Blob>;
+    download(options?: FileDownloadOptions): Promise<Blob>;
     tree(path?: string): Promise<string>;
     protected handleError(e: unknown): never;
 }

package/dist/filesystem.js

@@ -84,11 +84,125 @@ 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 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);
+        }
     }
-    write(path, contents) {
-        return this.okra.invoke('fs.write', { path, contents: contents });
+    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: (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);
+                }
+            },
+        });
     }
     find(query, options = {
         useIgnoreFiles: false,
@@ -169,56 +283,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));
@@ -251,17 +347,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());
     }
@@ -275,3 +371,25 @@ 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;
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+        length += chunk.byteLength;
+    }
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}