@phpsandbox/sdk 0.6.0-canary.3 → 0.6.0-canary.4

package/README.md

@@ -209,6 +209,32 @@ const [hasMore, matches] = await notebook.files.search(
 );
 ```
 
+`files.download()` returns a `ReadableStream<Uint8Array>` containing the notebook ZIP.
+Read it incrementally or pipe it to a writable stream:
+
+```ts
+const controller = new AbortController();
+const archive = notebook.files.download({
+  include: ['src/**'],
+  exclude: ['vendor/**'],
+  signal: controller.signal,
+});
+
+for await (const chunk of archive) {
+  await consume(chunk);
+}
+```
+
+Downloads use HTTP for both realtime and REST clients and require the runtime's
+`POST /api/v1/notebooks/{notebook}/runtime/files/download` endpoint. Reading starts
+the request; cancelling the stream, aborting its signal, or disposing the notebook
+stops the transfer. Failures reject stream reads and are not retried after bytes
+have started arriving.
+
+**Breaking change in 0.6.0-canary.4:** downloads no longer return a `Blob` or accept
+`onChunk`. If you need a Blob, explicitly collect the archive with
+`await new Response(notebook.files.download()).blob()`; this buffers the ZIP in memory.
+
 ### Terminal
 
 ```ts

package/dist/browser/phpsandbox-sdk.esm.js

@@ -16372,17 +16372,14 @@ var Filesystem = class {
   exists(path) {
     return this.stat(path).then(() => true).catch(() => false);
   }
-  async download(options = {}) {
-    const id = nanoid3();
-    const stream = !!options.onChunk;
-    const chunks = [];
-    const disposable = this.okra.listen(
-      `fs.download.${id}`,
-      stream ? options.onChunk : (data) => {
-        chunks.push(data);
+  download(options = {}) {
+    return this.okra.stream(
+      "fs.download",
+      { include: options.include, exclude: options.exclude },
+      {
+        abortSignal: options.signal
       }
     );
-    return this.okra.invoke("fs.download", { id, exclude: options.exclude, include: options.include }).then(() => new Blob(chunks, { type: "application/octet-stream" })).finally(() => disposable.dispose());
   }
   tree(path = "/") {
     return this.okra.invoke("fs.tree", { path });
@@ -20343,6 +20340,7 @@ var restActionRoutes = {
   "shell.exec": { method: "POST", path: "/runtime/executions" },
   "fs.readFile": { method: "GET", path: "/runtime/files/content" },
   "fs.writeFile": { method: "PUT", path: "/runtime/files/content" },
+  "fs.download": { method: "POST", path: "/runtime/files/download" },
   "fs.createDirectory": { method: "PUT", path: "/runtime/directories" },
   "fs.readDirectory": { method: "POST", path: "/runtime/directories/read" },
   "fs.stat": { method: "POST", path: "/runtime/files/stat" },
@@ -20379,6 +20377,7 @@ var RestRuntimeInvoker = class {
     this.fetch = fetch;
     this.refresh = refresh;
     this.refreshPromise = null;
+    this.streams = /* @__PURE__ */ new Set();
     this.notebookId = data.id;
     this.configure(data.runtimeUrl);
   }
@@ -20411,6 +20410,127 @@ var RestRuntimeInvoker = class {
   send() {
     throw new PHPSandboxError("Fire-and-forget actions require the realtime transport.");
   }
+  dispose() {
+    for (const stream of this.streams) {
+      stream.abort(new DOMException("Notebook disposed", "AbortError"));
+    }
+  }
+  stream(action, data, options = {}) {
+    const cancellation = new AbortController();
+    this.streams.add(cancellation);
+    const abort = runtimeAbort({ ...options, abortSignal: cancellation.signal });
+    const abortFromCaller = () => cancellation.abort(options.abortSignal?.reason);
+    let reader;
+    let closed = false;
+    let onAbort = () => {
+    };
+    const dispose = () => {
+      this.streams.delete(cancellation);
+      options.abortSignal?.removeEventListener("abort", abortFromCaller);
+      abort.signal.removeEventListener("abort", onAbort);
+      abort.dispose();
+    };
+    const cancelReader = async (reason) => {
+      const activeReader = reader;
+      reader = void 0;
+      if (activeReader !== void 0) {
+        await activeReader.cancel(reason).catch(() => void 0);
+        activeReader.releaseLock();
+      }
+    };
+    return new ReadableStream(
+      {
+        start: (controller) => {
+          onAbort = () => {
+            if (closed) {
+              return;
+            }
+            closed = true;
+            dispose();
+            controller.error(abort.signal.reason);
+            void cancelReader(abort.signal.reason);
+          };
+          abort.signal.addEventListener("abort", onAbort, { once: true });
+          options.abortSignal?.addEventListener("abort", abortFromCaller, { once: true });
+          if (options.abortSignal?.aborted) {
+            abortFromCaller();
+          }
+        },
+        pull: async (controller) => {
+          try {
+            if (reader === void 0) {
+              const response = await this.streamResponse(action, data, abort.signal);
+              if (closed) {
+                await response.body?.cancel();
+                return;
+              }
+              if (response.body === null) {
+                throw new TransportError("PHPSandbox runtime returned an empty download.", "InvalidResponse", response);
+              }
+              reader = response.body.getReader();
+            }
+            const result = await reader.read();
+            if (closed) {
+              return;
+            }
+            if (result.done) {
+              closed = true;
+              dispose();
+              reader.releaseLock();
+              reader = void 0;
+              controller.close();
+            } else {
+              controller.enqueue(result.value);
+            }
+          } catch (error51) {
+            if (!closed) {
+              closed = true;
+              cancellation.abort(error51);
+              dispose();
+              await cancelReader(error51);
+              controller.error(error51);
+            }
+          }
+        },
+        cancel: async (reason) => {
+          closed = true;
+          cancellation.abort(reason);
+          dispose();
+          await cancelReader(reason);
+        }
+      },
+      { highWaterMark: 0 }
+    );
+  }
+  async streamResponse(action, data, signal) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      signal.throwIfAborted();
+      const response = await runtimeFetch(this.fetch, this.request(action, data, signal));
+      if (signal.aborted) {
+        await response.body?.cancel();
+        signal.throwIfAborted();
+      }
+      if (response.status === 401 && attempt === 0 && this.refresh !== void 0) {
+        await response.body?.cancel();
+        await this.refreshAuthorization();
+        continue;
+      }
+      if (!response.ok) {
+        const payload = await runtimeActionResponse(response);
+        throw remoteError("runtime", payload.error, response);
+      }
+      if (!response.headers.get("content-type")?.toLowerCase().startsWith("application/zip")) {
+        await response.body?.cancel();
+        throw new TransportError("PHPSandbox runtime returned an invalid download.", "InvalidResponse", response);
+      }
+      return response;
+    }
+    throw new RemoteError("Notebook download could not be authorized.", {
+      source: "runtime",
+      status: 401,
+      code: "AuthenticationRequired"
+    });
+  }
   async invokeRaw(action, data, options) {
     const abort = runtimeAbort(options);
     try {
@@ -20443,7 +20563,7 @@ var RestRuntimeInvoker = class {
     const url2 = new URL(this.actionUrl);
     url2.pathname += route.path;
     const headers = {
-      Accept: "application/json, application/octet-stream",
+      Accept: action === "fs.download" ? "application/zip" : "application/json, application/octet-stream",
       Authorization: `Bearer ${this.ticket}`
     };
     const body = runtimeActionRequestBody(action, data, url2, headers);
@@ -20948,6 +21068,7 @@ var _NotebookInstance = class _NotebookInstance {
     this.data = data;
     this.client = client;
     __privateAdd(this, _NotebookInstance_instances);
+    this.downloadInvoker = null;
     this.initialized = false;
     __privateAdd(this, _initPromise, null);
     this.disposables = [];
@@ -21069,12 +21190,23 @@ var _NotebookInstance = class _NotebookInstance {
     }
     return this.realtimeSocket().send(action, data || {});
   }
+  /** Binary downloads use HTTP independently of the selected runtime transport. */
+  stream(action, data = {}, options = {}) {
+    const runtimeUrlProvider = this.client.options.runtimeUrlProvider;
+    this.downloadInvoker ?? (this.downloadInvoker = this.restInvoker ?? new RestRuntimeInvoker(
+      this.data,
+      this.client.options.fetch ?? globalThis.fetch,
+      runtimeUrlProvider === void 0 ? void 0 : () => runtimeUrlProvider(this.data.id)
+    ));
+    return this.downloadInvoker.stream(action, data, options);
+  }
   listen(event, handler) {
     const disposable = this.emitter.listen(event, handler);
     this.disposables.push(disposable);
     return disposable;
   }
   dispose() {
+    this.downloadInvoker?.dispose();
     this.disposables.forEach((d) => d.dispose());
     if (this.socket !== null && !this.socket.isClosed) {
       this.socket.disconnect();