@sasjs/api 0.4.0 → 0.6.0

package/build/cjs/routes/overlay.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.METHODS = exports.OVERLAY = exports.TAG_CAPABILITIES = void 0;
+const deploy_js_1 = require("../drive/deploy.js");
 /** The default capability for each tag, overridden per route where it differs. */
 exports.TAG_CAPABILITIES = {
     Drive: ['storage'],
@@ -17,6 +18,23 @@ exports.TAG_CAPABILITIES = {
     Client: ['identity'],
     Web: ['identity']
 };
+/**
+ * Why a block of operations is not implemented here.
+ *
+ * One per dependency rather than one per route: the reason states what the
+ * operation waits on, and thirty copies of the same sentence would say the same
+ * thing thirty times.
+ */
+const IDENTITY_RECORDS = 'The identity service answers the sign-in flow. User, group, permission rule, client and provider records need read and write methods on the same store, which this package does not have yet.';
+const EDITOR = 'Linting and formatting come from @sasjs/lint, which this package does not depend on. They land with the code routes so an editor has one wiring.';
+const RUNTIME = 'Starting a program needs a runtime port, which this package does not have: a host decides which languages it holds, and answers this itself until then.';
+const SESSION_RECORD = "A triggered session's record, log, output and state belong to the runtime that ran the program, and this package has no runtime port.";
+const HOST_CONFIG = "The body is the host's own configuration - ports, run times and providers - which a mock states for itself and this package cannot know.";
+const PERMISSIONS = "The route inventory is the host's permission model, which this package does not hold.";
+const HOST_OWNED = "The host owns this report: it describes the host's own process and files, which a browser build has no equivalent of.";
+const WEB_BUNDLE = 'The host serves its own web bundle; there is no API decision here for this package to answer.';
+const ARCHIVE = "Expanding the uploaded archive is the host's transport work - multer and a zip library on the server, `DecompressionStream` in a worker - and the host hands this package the tree it produces, which is the same tree `POST /SASjsApi/drive/deploy` takes.";
+const UNPUBLISH = 'Unpublishing inverts the deploy route, so the two land together.';
 const success = { status: 'success' };
 const user = {
     uid: '',
@@ -26,11 +44,61 @@ const user = {
     needsToUpdatePassword: false
 };
 exports.OVERLAY = {
-    // the route inventory reports what the CALLER may use, so it needs an identity
-    // even though the rest of the Info tag needs nothing
-    'GET /SASjsApi/info/authorizedRoutes': { capabilities: ['identity'] },
-    'GET /SASjsApi/info/myAuthorizedRoutes': { capabilities: ['identity'] },
-    // the body is the file itself, so there is nothing to annotate
+    // Web - the sign-in pages the identity service answers, and the bundle itself
+    'GET /': { implemented: false, reason: WEB_BUNDLE },
+    'POST /SASLogon/login': {
+        implemented: true,
+        // The lockout and the provider failure are answered before the package is
+        // consulted (routes/web/web.ts in sasjs/server).
+        hostResponses: [429, 500],
+        responses: { 200: { loggedIn: true, user } }
+    },
+    'POST /SASLogon/authorize': {
+        implemented: true,
+        responses: { 200: { code: '' } }
+    },
+    'GET /SASLogon/logout': {
+        implemented: true,
+        hostResponses: [500],
+        responses: { 200: 'OK!' }
+    },
+    // Admin - the host's own process and files
+    'GET /SASjsApi/admin/diagnostics': { implemented: false, reason: HOST_OWNED },
+    'GET /SASjsApi/admin/logs': { implemented: false, reason: HOST_OWNED },
+    'GET /SASjsApi/admin/logs/{fileName}': {
+        implemented: false,
+        reason: HOST_OWNED
+    },
+    // Auth - the token flow, plus a password change the identity store cannot write
+    'POST /SASjsApi/auth/token': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/refresh': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/logout': { implemented: true },
+    'PATCH /SASjsApi/auth/updatePassword': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Auth Config - the providers a host was started with, and an LDAP import
+    'GET /SASjsApi/authConfig': { implemented: false, reason: HOST_CONFIG },
+    'POST /SASjsApi/authConfig/synchroniseWithLDAP': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Client - the OAuth clients the identity store already holds for sign-in
+    'GET /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    // Code - the editor's three calls, and the runtime one
+    'POST /SASjsApi/code/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/code/trigger': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/code/lint': { implemented: false, reason: EDITOR },
+    'POST /SASjsApi/code/format': { implemented: false, reason: EDITOR },
+    // Drive - the file and folder rules, and the three deploy routes
+    // The body is the file itself, so there is nothing to annotate
     'GET /SASjsApi/drive/file': { implemented: true },
     'POST /SASjsApi/drive/file': {
         implemented: true,
@@ -68,54 +136,127 @@ exports.OVERLAY = {
         implemented: true,
         responses: { 200: { status: 'success', tree: {} } }
     },
-    // The two deploy routes write a whole tree in one request. They are the only
-    // ones where a caller can exhaust the host's storage, so they carry a cap -
-    // see the plan in sasjs/cli#1550 - and they are not implemented yet.
+    // The deploy routes answer an ENVELOPE, unlike the file routes above: their
+    // `400` is `{status:'failure', message}` rather than the message as text, and
+    // `413` is the cap refusing the tree before anything is written.
+    // `"appLoc" is required` and `"fileTree" is required` are the other `400` this
+    // route sends - a missing body property, worded by the table's own
+    // validation - so the body annotated here is the substantial one.
     'POST /SASjsApi/drive/deploy': {
-        implemented: false
+        implemented: true,
+        responses: {
+            200: deploy_js_1.DEPLOY_SUCCESS,
+            400: {
+                status: 'failure',
+                message: 'Provided not supported data format.'
+            },
+            413: 'The file tree exceeds the deploy limit.',
+            500: { status: 'failure', message: 'Deployment failed!' }
+        }
     },
     'POST /SASjsApi/drive/deploy/upload': {
-        implemented: false
-    },
-    // Unpublishing is the counterpart of the two above and lands with them: the
-    // document in sasjs/server states it (sasjs/server#543), so a host may answer
-    // it in the meantime, but this package cannot until the publish side it would
-    // invert is implemented here. The statuses are the document's; `404` is a pair
-    // - the registry name and the appLoc it was published from - that matches no
-    // entry, and the drive's content is deliberately left alone.
+        implemented: false,
+        reason: ARCHIVE
+    },
+    // `404` is a pair - the registry name and the appLoc it was published from -
+    // that matches no entry, and the drive's content is deliberately left alone.
     'DELETE /SASjsApi/drive/deploy': {
-        implemented: false
+        implemented: false,
+        reason: UNPUBLISH
     },
-    // The lockout and the provider failure are answered before the package is
-    // consulted (routes/web/web.ts in sasjs/server).
-    'POST /SASLogon/login': {
-        implemented: true,
-        hostResponses: [429, 500],
-        responses: { 200: { loggedIn: true, user } }
+    // Group - members and the groups themselves
+    'GET /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/group/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/group/by/groupname/{name}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     },
-    // The sign-in flow. The statuses are the document's; these entries state the
-    // body a client keys on, and that this package answers the operation.
-    'POST /SASjsApi/auth/token': {
-        implemented: true,
-        responses: { 200: { accessToken: '', refreshToken: '' } }
+    'POST /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/group/{groupUid}/{userUid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     },
-    'POST /SASjsApi/auth/refresh': {
-        implemented: true,
-        responses: { 200: { accessToken: '', refreshToken: '' } }
+    'DELETE /SASjsApi/group/{groupUid}/{userUid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     },
-    'POST /SASjsApi/auth/logout': { implemented: true },
-    'POST /SASLogon/authorize': {
-        implemented: true,
-        responses: { 200: { code: '' } }
+    'DELETE /SASjsApi/group/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     },
-    'GET /SASLogon/logout': {
-        implemented: true,
-        hostResponses: [500],
-        responses: { 200: 'OK!' }
+    // Info - what the host is, and what this caller may use
+    'GET /SASjsApi/info': { implemented: false, reason: HOST_CONFIG },
+    'GET /SASjsApi/info/authorizedRoutes': {
+        implemented: false,
+        // the route inventory reports what the CALLER may use, so it needs an
+        // identity even though the rest of the Info tag needs nothing
+        capabilities: ['identity'],
+        reason: PERMISSIONS
+    },
+    'GET /SASjsApi/info/myAuthorizedRoutes': {
+        implemented: false,
+        capabilities: ['identity'],
+        reason: PERMISSIONS
     },
+    // Permission - the rules the inventory above is derived from
+    'GET /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
+    'PATCH /SASjsApi/permission/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/permission/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Session - the caller's own session, then the record behind a triggered one
     'GET /SASjsApi/session': {
         implemented: true,
         responses: { 200: user }
+    },
+    'GET /SASjsApi/session/{sessionId}': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/log': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/output': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/state': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    // STP - a stored program, on the runtime port
+    'GET /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/stp/trigger': { implemented: false, reason: RUNTIME },
+    // User - the accounts the identity store already holds for sign-in
+    'GET /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/user/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'POST /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
+    'PATCH /SASjsApi/user/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'PATCH /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/user/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     }
 };
 /** Every method the table may state, in the order a diff reads best. */

package/build/cjs/types.js

@@ -16,9 +16,19 @@ exports.isApiError = exports.ApiError = void 0;
  * corpus can assert on the pair.
  */
 class ApiError extends Error {
-    constructor(status, message) {
+    constructor(status, message, 
+    /**
+     * The body the route renders instead of the bare message.
+     *
+     * Most drive routes send the message as text (`res.status(code).send(err)`),
+     * and that stays the default: a body here is for the routes that answer an
+     * envelope, which today is the two deploy routes and their
+     * `{status: 'failure', message}`.
+     */
+    body) {
         super(message);
         this.status = status;
+        this.body = body;
         /** Told apart by marker rather than `instanceof` - see `isApiError`. */
         this.apiError = true;
         this.name = 'ApiError';

package/build/esm/corpus/drive.d.ts

@@ -23,6 +23,12 @@ export interface CorpusCase {
     seed?: Record<string, string | Uint8Array>;
     /** The identity the case starts from; the default fixture when omitted. */
     identity?: IdentityFixture;
+    /**
+     * The drive refuses every write, so a case can pin the refusal a route answers
+     * when storing fails - `POST /drive/deploy` documents a `500`, and a mock drive
+     * that always accepts writes could never produce one.
+     */
+    unwritable?: boolean;
     request: ApiRequest;
     expect: {
         status: number;

package/build/esm/corpus/drive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/corpus/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9B,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC;;;WAGG;QACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;CACF;AAWD,eAAO,MAAM,YAAY,EAAE,UAAU,EA8SpC,CAAA"}
+{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../src/corpus/drive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,UAAU,CAAA;IACnB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;QAC9B,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAA;QACd;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC;;;WAGG;QACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAChB,CAAA;CACF;AAmBD,eAAO,MAAM,YAAY,EAAE,UAAU,EAqapC,CAAA"}

package/build/esm/corpus/drive.js

@@ -5,6 +5,12 @@ const success = { status: 'success' };
  * host that does not have one. An explicit byte array is both.
  */
 const bytes = (...values) => Uint8Array.from(values);
+/** A flat tree of `count` empty file members, for the cap's entry dimension. */
+const manyMembers = (count) => Array.from({ length: count }, (_, at) => ({
+    name: `f${at}.txt`,
+    type: 'file',
+    code: ''
+}));
 export const DRIVE_CORPUS = [
     {
         id: 'create-file',
@@ -294,6 +300,119 @@ export const DRIVE_CORPUS = [
             }
         }
     },
+    {
+        id: 'deploy-tree',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'writes a whole tree under the appLoc it names',
+        request: {
+            body: {
+                appLoc: '/Public/apps/demo',
+                fileTree: {
+                    members: [
+                        {
+                            name: 'services',
+                            type: 'folder',
+                            members: [{ name: 'run', type: 'service', code: '%put hi;' }]
+                        },
+                        { name: 'index.html', type: 'file', code: 'PGgxPkhlbGxvPC9oMT4=' }
+                    ]
+                }
+            }
+        },
+        expect: {
+            status: 200,
+            body: {
+                status: 'success',
+                message: 'Files deployed successfully to @sasjs/server.'
+            }
+        }
+    },
+    {
+        id: 'deploy-refused-by-entry-count',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses a tree over the entry cap, naming the figure and the cap',
+        request: {
+            body: {
+                appLoc: '/Public/apps/many',
+                fileTree: { members: manyMembers(10001) }
+            }
+        },
+        expect: {
+            status: 413,
+            body: {
+                status: 'failure',
+                message: 'The file tree exceeds the deploy limit: 10001 entries (maximum 10000).'
+            },
+            error: 'The file tree exceeds the deploy limit: 10001 entries (maximum 10000).'
+        }
+    },
+    {
+        id: 'deploy-refused-by-name',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses a member name that would escape the deployment root',
+        request: {
+            body: {
+                appLoc: '/Public/apps/hostile',
+                fileTree: {
+                    members: [{ name: '../escape', type: 'service', code: '%put hi;' }]
+                }
+            }
+        },
+        expect: {
+            status: 400,
+            body: {
+                status: 'failure',
+                message: "Invalid member name: '../escape.sas'. Member names must be single path segments (no '/', '\\', '..')."
+            },
+            error: "Invalid member name: '../escape.sas'. Member names must be single path segments (no '/', '\\', '..')."
+        }
+    },
+    {
+        id: 'deploy-refused-by-shape',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses a fileTree that is not a tree, in the routes own envelope',
+        request: { body: { appLoc: '/Public/apps/bad', fileTree: { members: 1 } } },
+        expect: {
+            status: 400,
+            body: {
+                status: 'failure',
+                message: 'Provided not supported data format.'
+            },
+            error: 'Provided not supported data format.'
+        }
+    },
+    {
+        id: 'deploy-refused-by-store',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'answers the routes 500 when the drive refuses the write',
+        unwritable: true,
+        request: {
+            body: {
+                appLoc: '/Public/apps/demo',
+                fileTree: {
+                    members: [{ name: 'run', type: 'service', code: '%put hi;' }]
+                }
+            }
+        },
+        expect: {
+            status: 500,
+            body: { status: 'failure', message: 'Deployment failed!' },
+            error: 'Deployment failed!'
+        }
+    },
+    {
+        id: 'deploy-refused-outside-drive',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses an appLoc that resolves outside the drive',
+        request: {
+            body: { appLoc: '/../outside', fileTree: { members: [] } }
+        },
+        expect: {
+            status: 400,
+            body: { status: 'failure', message: 'appLoc cannot be outside drive.' },
+            error: 'appLoc cannot be outside drive.'
+        }
+    },
     {
         id: 'bytes-round-trip',
         route: 'GET /SASjsApi/drive/file',

package/build/esm/corpus/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/corpus/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAQnD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,UAAU,KAAG,QAKjD,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAClB,UAAU,UAAU,EACpB,WAAU,QAAgC,KACzC,OAAO,CAAC,UAAU,CAcpB,CAAA"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/corpus/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAQnD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,UAAU,KAAG,QASjD,CAAA;AAkBF;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAClB,UAAU,UAAU,EACpB,WAAU,QAAgC,KACzC,OAAO,CAAC,UAAU,CAepB,CAAA"}

package/build/esm/corpus/runner.js

@@ -12,9 +12,25 @@ import { isApiError } from '../types.js';
  * mid-flow can declare the tokens and codes it begins with.
  */
 export const servicesFor = (testCase) => ({
-    drive: createDriveService(new MemoryDriveStore(testCase.seed || {})),
+    drive: createDriveService(testCase.unwritable
+        ? new RefusingDriveStore(testCase.seed || {})
+        : new MemoryDriveStore(testCase.seed || {})),
     identity: createIdentityService(new MemoryIdentityStore(testCase.identity || DEFAULT_IDENTITY))
 });
+/**
+ * A drive that reads but refuses every write.
+ *
+ * Only the corpus uses it: `POST /drive/deploy` answers `500` when storing
+ * fails, and a case for that answer needs a store that fails.
+ */
+class RefusingDriveStore extends MemoryDriveStore {
+    async write() {
+        throw new Error('the store refused the write');
+    }
+    async mkdirp() {
+        throw new Error('the store refused the write');
+    }
+}
 /**
  * Runs a corpus case against the drive the case seeds itself, or against
  * services a caller supplies - that is how a host (or a failing store) is put
@@ -33,7 +49,7 @@ export const runCase = async (testCase, services = servicesFor(testCase)) => {
         // only a refusal the API decided on becomes a status; anything else is a
         // broken host, and reporting it as a 500 would hide it from the suite
         if (isApiError(error))
-            return { status: error.status, error: error.message };
+            return { status: error.status, body: error.body, error: error.message };
         throw error;
     }
 };

package/build/esm/drive/deploy.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Deploying a file tree, and the cap that bounds it.
+ *
+ * `POST /SASjsApi/drive/deploy` writes a whole tree in one request, which makes
+ * it the one drive operation where a caller can fill the host's storage: the
+ * others write a single file at a time, bounded by the host's upload limit. So
+ * the tree is measured and its names checked BEFORE anything is written, and a
+ * refusal leaves the drive exactly as it was.
+ *
+ * The numbers live here rather than in a host, because both hosts answer the
+ * same `413` and a corpus case pins the wording: a limit stated twice is a limit
+ * that disagrees with itself in the release nobody re-read.
+ *
+ * Nothing here imports a runtime. A base64 file member is decoded by hand and a
+ * service's size is counted as UTF-8 by hand, because the same build runs in a
+ * service worker where `Buffer` does not exist and the package compiles against
+ * `lib: ES2020` with no ambient types.
+ */
+import type { DriveStore } from '../types.js';
+/** The three member kinds the wire format carries. */
+export type DeployMemberType = 'folder' | 'service' | 'file';
+export interface DeployFolderMember {
+    name: string;
+    type: 'folder';
+    members: DeployMember[];
+}
+/** A program; written as `<name>.sas`, its `code` being the program text. */
+export interface DeployServiceMember {
+    name: string;
+    type: 'service';
+    code: string;
+}
+/** A file; `code` is base64 of the bytes to write. */
+export interface DeployFileMember {
+    name: string;
+    type: 'file';
+    code: string;
+}
+export type DeployMember = DeployFolderMember | DeployServiceMember | DeployFileMember;
+export interface DeployTree {
+    members: DeployMember[];
+}
+/**
+ * The deploy cap, in binary megabytes (the unit a host's upload limit reports)
+ * and compared inclusively: a tree of exactly 10,000 entries and exactly 100 MB
+ * passes.
+ *
+ * The three dimensions fail differently and so are separate: an estate is many
+ * small files (`entries`), a compiled service is one large file (`fileBytes`),
+ * and the total is what the host holds in memory before the tree reaches the
+ * drive (`totalBytes`).
+ */
+export interface DeployLimits {
+    readonly entries: number;
+    readonly totalBytes: number;
+    readonly fileBytes: number;
+}
+export declare const DEPLOY_LIMITS: DeployLimits;
+/**
+ * The largest a deploy tree can be on the wire, which is what a host's transport
+ * has to admit.
+ *
+ * The cap is stated in DECODED bytes; the tree travels as JSON in which a file
+ * member's contents are base64 - 4/3 of what they write - and a service's are
+ * escaped text (~1.04). A tree at `totalBytes` therefore reaches the parser at
+ * up to ~134MB, and a transport that admits less refuses first with its own
+ * shape, so the cap it was meant to enforce is never consulted. 140MB leaves
+ * room for the tree's JSON scaffolding.
+ *
+ * Only the deploy routes use it: everywhere else a smaller limit applies,
+ * because a body is buffered before authentication and nothing else needs the
+ * headroom.
+ */
+export declare const DEPLOY_PAYLOAD_BYTES: number;
+/**
+ * The body a deploy answers success with.
+ *
+ * The wording is the published contract - a client may key on the message - so
+ * it is one constant here rather than a string in each host. It names
+ * `@sasjs/server` because that is the document's example, which predates this
+ * package; changing it is a document change, not a host's choice.
+ */
+export declare const DEPLOY_SUCCESS: {
+    readonly status: "success";
+    readonly message: "Files deployed successfully to @sasjs/server.";
+};
+/** The refusal a deploy earns, in the shape the deploy routes render. */
+export interface DeployRefusal {
+    code: 400 | 413;
+    status: 'failure';
+    message: string;
+}
+export interface DeployMeasurements {
+    entries: number;
+    totalBytes: number;
+    /** The largest single member, by decoded size, with its path in the tree. */
+    largest: {
+        path: string;
+        bytes: number;
+    };
+}
+/** The bytes a base64 body decodes to, for a store that writes bytes. */
+export declare const decodeBase64: (value: string) => Uint8Array;
+/**
+ * Measures a tree without touching a drive.
+ *
+ * Every member is counted, whatever its name: this answers "how big is this
+ * tree", and a caller that also needs the names checked is `checkDeployTree`.
+ */
+export declare const measureDeployTree: (members: DeployMember[]) => DeployMeasurements;
+/**
+ * The refusal a file tree earns, or `null` when it can be written.
+ *
+ * Names are checked first, then the dimensions in a fixed order - entries,
+ * total, single file - so a tree breaching two of them is refused for the same
+ * one every time, which is what lets a caller key on the message and a test pin
+ * it.
+ *
+ * `limits` defaults to `DEPLOY_LIMITS`; a host may pass its own, stricter set.
+ */
+export declare const checkDeployTree: (members: DeployMember[], limits?: DeployLimits) => DeployRefusal | null;
+/**
+ * The tree's shape, as the wire format states it.
+ *
+ * A port of `isFileTree` from `@sasjs/utils`, which is what sasjs/server
+ * validates with: a tree is an object with a `members` array, and every member
+ * is a folder with its own members, or a service/file with a string `code` and
+ * a string `name`. Anything else is the `400` the routes already answer.
+ */
+export declare const isDeployTree: (value: unknown) => value is DeployTree;
+/**
+ * Deploys a tree into `appLoc`, or refuses without writing.
+ *
+ * The order is the promise: shape, then containment, then the cap and the names,
+ * and only then the first write. `appLoc` is caller-supplied and every segment
+ * must stay a segment, so it is resolved against the drive root and refused when
+ * it leaves it - joined naively, a `..` would write outside the drive.
+ *
+ * A write that fails part-way answers the deploy routes' `500`; the tree before
+ * the failure is already on the drive, which the message does not hide.
+ */
+export declare const deployTree: (store: DriveStore, appLoc: unknown, tree: unknown, limits?: DeployLimits) => Promise<void>;
+//# sourceMappingURL=deploy.d.ts.map

package/build/esm/drive/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/drive/deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C,sDAAsD;AACtD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;AAE5D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,YAAY,GACtB,kBAAkB,GAAG,mBAAmB,GAAG,gBAAgB,CAAA;AAE7D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,eAAO,MAAM,aAAa,EAAE,YAI3B,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,QAAoB,CAAA;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;CAGjB,CAAA;AAEV,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,GAAG,GAAG,GAAG,CAAA;IACf,MAAM,EAAE,SAAS,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CACzC;AAiBD,yEAAyE;AACzE,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,UAmB5C,CAAA;AA8FD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,YAAY,EAAE,KACtB,kBAUF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,YAAY,EAAE,EACvB,SAAQ,YAA4B,KACnC,aAAa,GAAG,IA6BlB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,UAMtD,CAAA;AAkBD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,UAAU,EACjB,QAAQ,OAAO,EACf,MAAM,OAAO,EACb,SAAQ,YAA4B,KACnC,OAAO,CAAC,IAAI,CAiCd,CAAA"}