@sasjs/api 0.5.0 → 0.6.1

package/build/cjs/drive/deploy.js

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deployTree = exports.isDeployTree = exports.checkDeployTree = exports.measureDeployTree = exports.decodeBase64 = exports.MAX_DEPTH = exports.DEPLOY_SUCCESS = exports.DEPLOY_PAYLOAD_BYTES = exports.DEPLOY_LIMITS = void 0;
+const types_js_1 = require("../types.js");
+const paths_js_1 = require("./paths.js");
+exports.DEPLOY_LIMITS = {
+    entries: 10000,
+    totalBytes: 100 * 1024 * 1024,
+    fileBytes: 20 * 1024 * 1024
+};
+/**
+ * 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.
+ */
+exports.DEPLOY_PAYLOAD_BYTES = 140 * 1024 * 1024;
+/**
+ * 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.
+ */
+exports.DEPLOY_SUCCESS = {
+    status: 'success',
+    message: 'Files deployed successfully to @sasjs/server.'
+};
+/**
+ * How deep a tree may nest.
+ *
+ * A deployment is an app: `services/`, `web/`, a folder per service. A few dozen
+ * levels is generous, and the number matters because the walk recurses once per
+ * level - without a ceiling, a tree nested deeply enough exhausts the stack and
+ * throws a `RangeError`, which is neither the `400` nor the `413` this route
+ * documents, on input the cap exists to bound.
+ */
+exports.MAX_DEPTH = 32;
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** A base64 body without its padding, which is what the arithmetic needs. */
+const base64Body = (value) => value.replace(/[^A-Za-z0-9+/]/g, '');
+/** The bytes a base64 body decodes to, without decoding it. */
+const base64Length = (value) => Math.floor((base64Body(value).length * 3) / 4);
+/** The bytes a base64 body decodes to, for a store that writes bytes. */
+const decodeBase64 = (value) => {
+    const body = base64Body(value);
+    const bytes = new Uint8Array(Math.floor((body.length * 3) / 4));
+    let buffer = 0;
+    let bits = 0;
+    let at = 0;
+    for (const char of body) {
+        buffer = (buffer << 6) | BASE64_ALPHABET.indexOf(char);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[at++] = (buffer >> bits) & 0xff;
+        }
+    }
+    return bytes.subarray(0, at);
+};
+exports.decodeBase64 = decodeBase64;
+/** The bytes a string occupies as UTF-8, without an encoding API. */
+const utf8Length = (value) => {
+    let bytes = 0;
+    for (let at = 0; at < value.length; at++) {
+        const code = value.charCodeAt(at);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && at + 1 < value.length) {
+            // a surrogate pair is one code point of four bytes
+            bytes += 4;
+            at++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+};
+/** The name a member is written under - a service gains the extension. */
+const memberName = (member) => member.type === 'service' ? `${member.name}.sas` : member.name;
+/** The bytes a member writes. */
+const memberBytes = (member) => member.type === 'file' ? base64Length(member.code) : utf8Length(member.code);
+const MEGABYTE = 1024 * 1024;
+/**
+ * A MEASURED size, rounded UP to one decimal in binary megabytes.
+ *
+ * Up, not to nearest: a tree one byte over a 100 MB cap must not read as "100 MB
+ * (maximum 100 MB)", which is a refusal that states no overage at all. Rounding
+ * up is the direction that never understates what is being refused.
+ *
+ * Bytes below a megabyte are printed as bytes, because a limit small enough to
+ * be measured in bytes should not read as "0 MB" - which is what a host passing
+ * a tighter set would otherwise report.
+ */
+const describeSize = (bytes) => bytes < MEGABYTE
+    ? `${bytes} bytes`
+    : `${Math.ceil((bytes / MEGABYTE) * 10) / 10} MB`;
+/**
+ * A LIMIT, printed as it is stated: `DEPLOY_LIMITS` holds exact megabytes, so
+ * rounding cannot make it disagree with itself.
+ */
+const describeLimit = (bytes) => bytes < MEGABYTE
+    ? `${bytes} bytes`
+    : `${Math.round((bytes / MEGABYTE) * 10) / 10} MB`;
+/** A walk's starting point. */
+const emptyWalk = () => ({
+    entries: 0,
+    totalBytes: 0,
+    largest: { path: '', bytes: 0 }
+});
+/**
+ * Every member name becomes a path SEGMENT under the deployment root, so a name
+ * carrying '/', '\' or '..' is a traversal attempt rather than a name.
+ */
+const isSafeSegment = (name) => name !== '' &&
+    name !== '.' &&
+    name !== '..' &&
+    !/[/\\]/.test(name) &&
+    // a Windows drive or a NUL byte is never a segment either
+    !/[\0]/.test(name);
+/**
+ * Walks a tree, counting it and noting the first unsafe name.
+ *
+ * A name problem is RECORDED rather than returned, so the walk always finishes:
+ * a caller that only wants the numbers gets the size of the whole tree, and the
+ * validator decides whether the name matters. Returning early would report a
+ * truncated tree as if it were the real one.
+ *
+ * The one thing that stops the walk is depth: past `MAX_DEPTH` it does not
+ * descend, because descending is the work that would exhaust the stack. The
+ * level it reached is recorded so the refusal can state it.
+ */
+const walk = (members, parentPath, acc, depth = 1) => {
+    for (const member of members) {
+        const name = memberName(member);
+        const memberPath = parentPath ? `${parentPath}/${name}` : name;
+        if (!isSafeSegment(name) && !acc.nameRefusal)
+            acc.nameRefusal = {
+                code: 400,
+                status: 'failure',
+                message: `Invalid member name: '${name}'. Member names must be single path segments (no '/', '\\', '..').`
+            };
+        acc.entries++;
+        if (member.type === 'folder') {
+            if (depth + 1 > exports.MAX_DEPTH) {
+                if (!acc.tooDeep)
+                    acc.tooDeep = depth + 1;
+                continue;
+            }
+            walk(member.members, memberPath, acc, depth + 1);
+            continue;
+        }
+        const bytes = memberBytes(member);
+        acc.totalBytes += bytes;
+        if (bytes > acc.largest.bytes)
+            acc.largest = { path: memberPath, bytes };
+    }
+};
+/**
+ * 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`.
+ */
+const measureDeployTree = (members) => {
+    const acc = emptyWalk();
+    walk(members, '', acc);
+    return {
+        entries: acc.entries,
+        totalBytes: acc.totalBytes,
+        largest: acc.largest
+    };
+};
+exports.measureDeployTree = measureDeployTree;
+/**
+ * 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.
+ */
+const checkDeployTree = (members, limits = exports.DEPLOY_LIMITS) => {
+    const measured = emptyWalk();
+    walk(members, '', measured);
+    if (measured.nameRefusal)
+        return measured.nameRefusal;
+    if (measured.tooDeep)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `The file tree is nested too deeply: ${measured.tooDeep} levels (maximum ${exports.MAX_DEPTH}).`
+        };
+    if (measured.entries > limits.entries)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `The file tree exceeds the deploy limit: ${measured.entries} entries (maximum ${limits.entries}).`
+        };
+    if (measured.totalBytes > limits.totalBytes)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `The file tree exceeds the deploy limit: ${describeSize(measured.totalBytes)} (maximum ${describeLimit(limits.totalBytes)}).`
+        };
+    if (measured.largest.bytes > limits.fileBytes)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `A file in the tree exceeds the deploy limit: ${measured.largest.path} is ${describeSize(measured.largest.bytes)} (maximum ${describeLimit(limits.fileBytes)} per file).`
+        };
+    return null;
+};
+exports.checkDeployTree = checkDeployTree;
+/**
+ * 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.
+ */
+const isDeployTree = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const members = value.members;
+    return Array.isArray(members) && members.every(isDeployMember);
+};
+exports.isDeployTree = isDeployTree;
+const isDeployMember = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const member = value;
+    if (typeof member.name !== 'string')
+        return false;
+    if (member.type === 'folder')
+        return Array.isArray(member.members) && member.members.every(isDeployMember);
+    if (member.type === 'service' || member.type === 'file')
+        return typeof member.code === 'string';
+    return false;
+};
+/**
+ * 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.
+ */
+const deployTree = async (store, appLoc, tree, limits = exports.DEPLOY_LIMITS) => {
+    if (!(0, exports.isDeployTree)(tree))
+        throw new types_js_1.ApiError(400, 'Provided not supported data format.', {
+            status: 'failure',
+            message: 'Provided not supported data format.'
+        });
+    const root = (0, paths_js_1.normaliseDrivePath)(appLoc);
+    if (root === null)
+        throw new types_js_1.ApiError(400, 'appLoc cannot be outside drive.', {
+            status: 'failure',
+            message: 'appLoc cannot be outside drive.'
+        });
+    const refusal = (0, exports.checkDeployTree)(tree.members, limits);
+    // the body is the envelope WITHOUT the refusal's own `code`: that field is
+    // how a host turns the refusal into a status, and it is not sent
+    if (refusal)
+        throw new types_js_1.ApiError(refusal.code, refusal.message, {
+            status: refusal.status,
+            message: refusal.message
+        });
+    try {
+        await writeMembers(store, tree.members, root);
+    }
+    catch {
+        throw new types_js_1.ApiError(500, 'Deployment failed!', {
+            status: 'failure',
+            message: 'Deployment failed!'
+        });
+    }
+};
+exports.deployTree = deployTree;
+/** Writes every member under `parentPath`, depth first. */
+const writeMembers = async (store, members, parentPath) => {
+    for (const member of members) {
+        const path = `${parentPath}/${memberName(member)}`;
+        if (member.type === 'folder') {
+            await store.mkdirp(path);
+            await writeMembers(store, member.members, path);
+            continue;
+        }
+        await store.write(path, member.type === 'file' ? (0, exports.decodeBase64)(member.code) : member.code);
+    }
+};

package/build/cjs/drive/service.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDriveService = void 0;
 const types_js_1 = require("../types.js");
+const deploy_js_1 = require("./deploy.js");
 const paths_js_1 = require("./paths.js");
 /** A path a file operation may act on, or the refusal the operation answers. */
 const filePath = (input, outside) => {
@@ -145,6 +146,10 @@ const createDriveService = (store) => {
             if (!stat.directory)
                 throw new types_js_1.ApiError(400, 'Not a Folder.');
             return { status: 'success', tree: await treeOf(path) };
+        },
+        async deploy(appLoc, tree) {
+            await (0, deploy_js_1.deployTree)(store, appLoc, tree);
+            return { status: 'success' };
         }
     };
 };

package/build/cjs/host/dispatch.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HANDLED_ROUTES = exports.dispatch = void 0;
 const index_js_1 = require("../routes/index.js");
 const types_js_1 = require("../types.js");
+const deploy_js_1 = require("../drive/deploy.js");
 /**
  * The parameters the table marks required, checked before the handler runs.
  *
@@ -129,6 +130,12 @@ const dispatch = async (services, routeId, request = {}) => {
                 status: 200,
                 body: await drive.rename(String(request.body?.oldPath || ''), String(request.body?.newPath || ''))
             };
+        case 'POST /SASjsApi/drive/deploy': {
+            // `streamWebFolder` is the host's: publishing an app stream is not a drive
+            // operation, and a host that has no app stream ignores it.
+            await drive.deploy(String(body.appLoc ?? ''), body.fileTree);
+            return { status: 200, body: deploy_js_1.DEPLOY_SUCCESS };
+        }
         case 'GET /SASjsApi/drive/filetree':
             return { status: 200, body: await drive.tree(query._folderPath) };
         default: {
@@ -152,6 +159,7 @@ exports.HANDLED_ROUTES = [
     'DELETE /SASjsApi/drive/folder',
     'POST /SASjsApi/drive/rename',
     'GET /SASjsApi/drive/filetree',
+    'POST /SASjsApi/drive/deploy',
     'POST /SASjsApi/auth/token',
     'POST /SASjsApi/auth/refresh',
     'POST /SASjsApi/auth/logout',

package/build/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.servicesFor = exports.runCase = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
+exports.servicesFor = exports.runCase = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.measureDeployTree = exports.isDeployTree = exports.deployTree = exports.decodeBase64 = exports.checkDeployTree = exports.DEPLOY_SUCCESS = exports.DEPLOY_PAYLOAD_BYTES = exports.DEPLOY_LIMITS = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
 /**
  * `@sasjs/api` - the SASjs Server API described once.
  *
@@ -39,6 +39,15 @@ Object.defineProperty(exports, "basename", { enumerable: true, get: function ()
 Object.defineProperty(exports, "isRoot", { enumerable: true, get: function () { return paths_js_1.isRoot; } });
 var service_js_1 = require("./drive/service.js");
 Object.defineProperty(exports, "createDriveService", { enumerable: true, get: function () { return service_js_1.createDriveService; } });
+var deploy_js_1 = require("./drive/deploy.js");
+Object.defineProperty(exports, "DEPLOY_LIMITS", { enumerable: true, get: function () { return deploy_js_1.DEPLOY_LIMITS; } });
+Object.defineProperty(exports, "DEPLOY_PAYLOAD_BYTES", { enumerable: true, get: function () { return deploy_js_1.DEPLOY_PAYLOAD_BYTES; } });
+Object.defineProperty(exports, "DEPLOY_SUCCESS", { enumerable: true, get: function () { return deploy_js_1.DEPLOY_SUCCESS; } });
+Object.defineProperty(exports, "checkDeployTree", { enumerable: true, get: function () { return deploy_js_1.checkDeployTree; } });
+Object.defineProperty(exports, "decodeBase64", { enumerable: true, get: function () { return deploy_js_1.decodeBase64; } });
+Object.defineProperty(exports, "deployTree", { enumerable: true, get: function () { return deploy_js_1.deployTree; } });
+Object.defineProperty(exports, "isDeployTree", { enumerable: true, get: function () { return deploy_js_1.isDeployTree; } });
+Object.defineProperty(exports, "measureDeployTree", { enumerable: true, get: function () { return deploy_js_1.measureDeployTree; } });
 var memory_store_js_1 = require("./drive/memory-store.js");
 Object.defineProperty(exports, "MemoryDriveStore", { enumerable: true, get: function () { return memory_store_js_1.MemoryDriveStore; } });
 var index_js_1 = require("./routes/index.js");

package/build/cjs/routes/generated.js

@@ -472,6 +472,10 @@ exports.GENERATED_ROUTES = [
                 status: 400,
                 description: 'Invalid Format'
             },
+            {
+                status: 413,
+                description: 'File tree exceeds the deploy limit'
+            },
             {
                 status: 500,
                 description: 'Execution Error'
@@ -502,6 +506,10 @@ exports.GENERATED_ROUTES = [
                 status: 400,
                 description: 'Invalid Format'
             },
+            {
+                status: 413,
+                description: 'File tree exceeds the deploy limit'
+            },
             {
                 status: 500,
                 description: 'Execution Error'

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'],
@@ -32,7 +33,7 @@ const HOST_CONFIG = "The body is the host's own configuration - ports, run times
 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 DEPLOY_CAP = "Writing a whole tree in one request can exhaust the host's storage, so the deploy routes land with the size cap that bounds it.";
+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 = {
@@ -135,10 +136,27 @@ exports.OVERLAY = {
         implemented: true,
         responses: { 200: { status: 'success', tree: {} } }
     },
-    'POST /SASjsApi/drive/deploy': { implemented: false, reason: DEPLOY_CAP },
+    // 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: 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,
-        reason: DEPLOY_CAP
+        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.

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