@jxsuite/protocol 2.4.0 → 2.5.0

package/README.md

@@ -17,7 +17,7 @@ A backend is free to change the transport and path prefix; the **sub-path, metho
 
 ## Core vs optional
 
-Optional routes back optional `StudioPlatform` members. Omitting one is not an error. Studio degrades exactly as each entry's `degradation` describes (the starter picker empties, the Projects catalogue hides, the Publish panel explains git-push publishing, and so on). `coreRouteNames()` / `optionalRouteNames()` split the table programmatically; a conformance test for a new backend can iterate `STUDIO_ROUTES` and assert every core route is served.
+Optional routes back optional `StudioPlatform` members, or, like `filesRead`, back no member and let an adapter serve one it already has more cheaply (their `degradation` names the route they stand in for). Omitting one is not an error. Studio degrades exactly as each entry's `degradation` describes (the starter picker empties, the Projects catalogue hides, the Publish panel explains git-push publishing, and so on). `coreRouteNames()` / `optionalRouteNames()` split the table programmatically; a conformance test for a new backend can iterate `STUDIO_ROUTES` and assert every core route is served.
 
 Highlights an implementer should know:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -1,7 +1,6 @@
 /**
- * The Studio Backend Protocol package: wire types plus the canonical route
- * table every Jx Studio backend implements. See README.md for the implementer
- * guide.
+ * The Studio Backend Protocol package: wire types plus the canonical route table every Jx Studio
+ * backend implements. See README.md for the implementer guide.
  *
  * @license MIT
  */
@@ -10,3 +9,5 @@ export * from "./problem";
 export * from "./problems";
 export * from "./routes";
 export type * from "./types";
+// The one runtime value types.ts carries: the batch-read limit a backend and a client both size to.
+export { READ_FILES_MAX_PATHS } from "./types";

package/src/routes.ts

@@ -1,10 +1,10 @@
 /**
- * Studio Backend Protocol — the canonical route table. The dev server
- * (@jxsuite/server) is the reference implementation; every other backend
- * (desktop RPC bridge, cloud platforms) serves the same shapes, either at
- * these literal paths or through an equivalent transport. Optional routes
- * back optional StudioPlatform members — Studio degrades without them, as
- * described by each entry's `degradation`.
+ * Studio Backend Protocol — the canonical route table. The dev server (@jxsuite/server) is the
+ * reference implementation; every other backend (desktop RPC bridge, cloud platforms) serves the
+ * same shapes, either at these literal paths or through an equivalent transport. Optional routes
+ * mostly back optional StudioPlatform members — Studio degrades without them, as described by each
+ * entry's `degradation`. A few back no member at all: an adapter uses them to serve members it
+ * already has more cheaply (`filesRead`), and their `degradation` is the route they stand in for.
  *
  * @license MIT
  */
@@ -28,7 +28,10 @@ export type StudioRouteMethod = "GET" | "POST" | "PUT" | "DELETE";
 export interface StudioRoute {
   path: string;
   method: StudioRouteMethod;
-  /** True when a backend may omit the route (its PAL member is optional). */
+  /**
+   * True when a backend may omit the route: its PAL member is optional, or it has no member and an
+   * adapter falls back to another route.
+   */
   optional: boolean;
   /** One-line contract summary. */
   summary: string;
@@ -111,6 +114,31 @@ export const STUDIO_ROUTES = {
       "files project-wide",
   ),
   fileRead: route("GET", "/__studio/file", "Read a file's text content"),
+  /**
+   * Many reads in ONE round trip, for a backend whose every request is a network hop.
+   *
+   * The first optional route with no `StudioPlatform` member behind it: the PAL keeps `readFile`,
+   * and an adapter for such a backend coalesces the reads issued in one tick into this call itself
+   * (specs/desktop.md §3.1, §10.1). Callers never see it, so a backend without it costs latency and
+   * nothing else — which is why the dev server, whose reads are loopback, does not serve it.
+   *
+   * The answer is partial by design, never a 400: past `READ_FILES_MAX_PATHS` paths or the
+   * backend's byte budget, the rest come back in `omitted` for the client to ask again, and the
+   * first path is always answered so that asking again makes progress. Each answered path carries
+   * its own outcome, because one missing file is not a failed batch. It is a READ: a read-only
+   * session may call it, and whatever a single `fileRead` does on the backend's side (a cloud
+   * session fetches and stores the file it serves) this does per path too.
+   */
+  filesRead: route(
+    "POST",
+    "/__studio/files/read",
+    "Read many files' text content {paths} → ReadFilesResult {files: [path, {content} | " +
+      "{error: {status, code?, message}}][], omitted}. At most READ_FILES_MAX_PATHS (200) paths " +
+      "and a backend byte budget per call: the excess is listed in `omitted` (never a 400) and " +
+      "the first path is always answered. Per-path errors: 404 missing/deleted, 415 binary, 413 " +
+      "too large, 502 upstream. Allowed for read-only sessions; keeps fileRead's server-side effects",
+    "Adapters fall back to one fileRead per path.",
+  ),
   fileWrite: route("PUT", "/__studio/file", "Write a file's text content"),
   fileDelete: route("DELETE", "/__studio/file", "Delete a file"),
   fileUpload: route(
@@ -475,7 +503,10 @@ export function coreRouteNames(): StudioRouteName[] {
   );
 }
 
-/** Names of the optional routes (each backs an optional StudioPlatform member). */
+/**
+ * Names of the optional routes (each backs an optional StudioPlatform member, or is an adapter's
+ * optimisation with a fallback).
+ */
 export function optionalRouteNames(): StudioRouteName[] {
   return (Object.keys(STUDIO_ROUTES) as StudioRouteName[]).filter(
     (name) => STUDIO_ROUTES[name].optional,

package/src/types.ts

@@ -1,8 +1,7 @@
 /**
- * Studio Backend Protocol — wire types. Every shape a Studio backend serves
- * (or a `StudioPlatform` adapter consumes) lives here so client adapters and
- * server implementations (the dev server, the desktop RPC bridge, cloud
- * platforms) share one contract. Environment-agnostic: no DOM, no node —
+ * Studio Backend Protocol — wire types. Every shape a Studio backend serves (or a `StudioPlatform`
+ * adapter consumes) lives here so client adapters and server implementations (the dev server, the
+ * desktop RPC bridge, cloud platforms) share one contract. Environment-agnostic: no DOM, no node —
  * importable in browsers, Bun, and Cloudflare Workers alike.
  *
  * @license MIT
@@ -87,6 +86,45 @@ export interface UploadResult {
   size?: number;
 }
 
+/**
+ * The most paths one `filesRead` request may name. A backend answers at most this many and lists
+ * the rest under {@link ReadFilesResult.omitted}, so a client that sends more is not refused — it is
+ * answered in part, and asks again.
+ *
+ * The one runtime value in this file: a client sizes its batches to it, so it has to exist at
+ * runtime rather than only in a summary string.
+ */
+export const READ_FILES_MAX_PATHS = 200;
+
+/** Body of `POST /__studio/files/read` (`filesRead`): the project-relative paths to read. */
+export interface ReadFilesRequest {
+  paths: string[];
+}
+
+/**
+ * One path's answer inside a {@link ReadFilesResult}: its text, or why it has none.
+ *
+ * Per path rather than per request, because one unreadable file in a batch of two hundred is not a
+ * failed batch. `status` borrows the HTTP code the single-file read would have answered (404
+ * missing or deleted, 415 binary, 413 too large, 502 upstream), so a client can treat both routes'
+ * failures alike.
+ */
+export type ReadFilesOutcome =
+  | { content: string }
+  | { error: { status: number; code?: string; message: string } };
+
+/**
+ * Answer of `POST /__studio/files/read`. `files` pairs each answered path with its outcome;
+ * `omitted` lists the requested paths this response did not get to (a path or byte budget ran out).
+ * Omission is never an error and never a 400: the client asks for those paths again. A backend
+ * always answers the FIRST requested path, which is what guarantees that asking again makes
+ * progress.
+ */
+export interface ReadFilesResult {
+  files: [path: string, outcome: ReadFilesOutcome][];
+  omitted: string[];
+}
+
 /**
  * What a backend will accept as an upload, when it says.
  *