@sasjs/cli 6.27.3 → 6.29.0

package/build/commands/build/internal/mockSite/assets/intercept.js

@@ -97,15 +97,20 @@
     }
   }
 
-  const respond = (xhr, status, contentType, body) => {
+  const respond = (xhr, status, contentType, body, bytes) => {
     Object.defineProperty(xhr, 'status', { value: status, configurable: true })
     Object.defineProperty(xhr, 'statusText', {
       value: status === 200 ? 'OK' : 'ERROR',
       configurable: true
     })
     Object.defineProperty(xhr, 'readyState', { value: 4, configurable: true })
+    // `bytes` is set when the caller asked for a blob or an arraybuffer. The
+    // drive serves PNGs, PDFs and workbooks, and answering a blob request with
+    // the body decoded as text hands `<img>` mojibake - which is how a picture
+    // on the site came to fail to render with an "Abort" modal.
+    const binary = bytes !== undefined
     Object.defineProperty(xhr, 'responseText', {
-      value: body,
+      value: binary ? '' : body,
       configurable: true
     })
     Object.defineProperty(xhr, 'responseURL', {
@@ -113,7 +118,16 @@
       configurable: true
     })
     Object.defineProperty(xhr, 'response', {
-      value: xhr.responseType === 'json' ? safeParse(body) : body,
+      value: binary
+        ? xhr.responseType === 'arraybuffer'
+          ? bytes.buffer.slice(
+              bytes.byteOffset,
+              bytes.byteOffset + bytes.byteLength
+            )
+          : new Blob([bytes], { type: contentType })
+        : xhr.responseType === 'json'
+          ? safeParse(body)
+          : body,
       configurable: true
     })
     xhr.getAllResponseHeaders = () => 'content-type: ' + contentType + '\r\n'
@@ -165,8 +179,30 @@
         )
 
         const res = await fetch(xhr.__sasjsMockUrl, init)
-        const text = await res.text()
         const contentType = res.headers.get('content-type') || 'text/plain'
+
+        // A caller that asked for bytes must be handed them as bytes: the same
+        // request answered with `res.text()` gives a PNG's UTF-8 damage, and the
+        // image or file the caller builds from it is unusable.
+        const wantsBytes =
+          xhr.responseType === 'blob' || xhr.responseType === 'arraybuffer'
+
+        if (wantsBytes) {
+          const bytes = new Uint8Array(await res.arrayBuffer())
+          if (res.status >= 400)
+            console.error(
+              '[sasjs-mock] ' +
+                xhr.__sasjsMockUrl +
+                ' -> ' +
+                res.status +
+                ' ' +
+                new TextDecoder().decode(bytes).slice(0, 400)
+            )
+          respond(xhr, res.status, contentType, '', bytes)
+          return
+        }
+
+        const text = await res.text()
         if (res.status >= 400)
           console.error(
             '[sasjs-mock] ' +

package/build/commands/build/internal/mockSite/assets/runtime-core.js

@@ -934,6 +934,32 @@ const formatArg = (a) => {
 
 const PROGRAM_FOLDERS = ['services', 'jobs', 'tests']
 
+/**
+ * The extensions an extension-less program is tried with, in the host's `RUN_TIMES` order.
+ *
+ * SASjs Server gives priority to the run time that comes first in `RUN_TIMES`
+ * (`docs/pages/settings.md`): with `RUN_TIMES=js,sas` a reference to `/some/program` finds
+ * `program.js` before `program.sas`. The order is the host's to declare, so this starts empty
+ * and the host sets it: guessing here would let a host that says nothing run a file its own
+ * `RUN_TIMES` does not offer.
+ */
+let RUN_TIME_EXTENSIONS = []
+
+/** Declare the host's run times, in its order. Their extensions are tried in that order. */
+const setRunTimes = (runTimes) => {
+  const extensions = (Array.isArray(runTimes) ? runTimes : [])
+    .map(
+      (runTime) =>
+        '.' +
+        String(runTime || '')
+          .trim()
+          .toLowerCase()
+    )
+    .filter((extension) => extension.length > 1)
+
+  if (extensions.length) RUN_TIME_EXTENSIONS = extensions
+}
+
 /**
  * Resolves a program reference the way the server does: an exact drive path,
  * with the runtime extension tried. The adapter sends a full path, and prepends
@@ -960,7 +986,10 @@ const resolveProgram = (program) => {
   }
 
   for (const root of roots) {
-    for (const candidate of [root, root + '.js', root + '.sas']) {
+    for (const candidate of [
+      root,
+      ...RUN_TIME_EXTENSIONS.map((extension) => root + extension)
+    ]) {
       if (FILES.has(candidate)) return candidate
     }
   }
@@ -1528,6 +1557,8 @@ const api = {
   // the file a program names, so the host can tell a .sas program from a .js one
   // and refuse the former instead of compiling SAS source as JavaScript
   resolveProgram: (program) => resolveProgram(program),
+  // the host's RUN_TIMES, so an extension-less program is probed in the order it declares
+  setRunTimes: (runTimes) => setRunTimes(runTimes),
   // the drive's bytes, for @sasjs/api's services: the rules that decide a
   // status are the package's, so this host hands over storage and nothing else
   driveStore,

package/build/commands/build/internal/mockSite/assets/sw.js

@@ -401,21 +401,83 @@ const persistChanges = async () => {
 /**
  * A recorded SAS session, for a project that ships one.
  *
- * A browser has no SAS binary. Rather than let a Run on a .sas program be a
- * surprise, a project may record a session once and commit it as
- * `sas-transcript.json`: the build copies it into the site and this answers a
- * run of a program it names with that session's log, listing and webout. The
- * recording is the demo's own data, so nothing here is invented for a project
- * that does not ship one - those runs reach the runner and are refused exactly
- * as before.
+ * A mock site is a JavaScript backend: there is no SAS binary here and never was, so a SAS
+ * run cannot be executed and cannot fail for want of the binary either. It answers with a
+ * session - the log, listing and webout a run of that program would have produced.
+ *
+ * By default that session is the mocked one below, which is the point of the mock: a visitor
+ * who edits a `.sas` file or runs a buffer sees the Studio's log panel the way a real run
+ * fills it, errors and warnings included, instead of being told about a binary a browser was
+ * never going to have.
+ *
+ * A project may record a real session and commit it as `sas-transcript.json`, and a run of a
+ * program it names is answered with that instead - the project's own output is better than
+ * ours, and a demo of a specific report wants the real numbers.
  *
  * Shape: `{ "<program path>": {"log": "...", "print": "...", "webout": "..."} }`,
  * all three strings. The path is matched as written apart from the
  * `/sasjs/drive/files` prefix and the `.sas` suffix, so a recording keeps the
  * path a person sees; a bare file name is not enough, because that would answer
- * every file of that name in the drive.
+ * every file of that name in the drive. `{{program}}` in any of the three strings is
+ * replaced with the program's logical path, so an answer can name what was run.
  */
 const SAS_TRANSCRIPT = 'host/sas-transcript.json'
+
+/**
+ * The session a SAS run is answered with when the project has not recorded one.
+ *
+ * Written the way a SAS log is written - source lines with their numbers, notes, a warning and
+ * an error, the process-time block - because the Studio parses this text: the log panel marks
+ * errors and warnings from it, and a demo whose mock answered with an empty log would show a
+ * panel that never lights up. The webout is what a service that sends data back would have
+ * written, and the listing is what `proc print` puts on a page.
+ */
+const MOCKED_SESSION = {
+  webout: '{"SYSSITE":"00000000","MOCKED":true}',
+  log: [
+    'NOTE: This is a mocked SAS session: a browser has no SAS binary.',
+    '      The program below is {{program}}.',
+    '',
+    '1    data work.class;',
+    '2      set sashelp.class;',
+    '3      where age > 12',
+    '4      by name;',
+    '5    run;',
+    '',
+    'ERROR 22-322: Syntax error, expecting one of the following: ;, DATA, DATALINES,',
+    '              DELETE, DESCRIBE, FILE, INPUT, LIST, MERGE, MODIFY, OUTPUT, PUT,',
+    '              SET, UPDATE.',
+    'ERROR 76-322: Syntax error, statement will be ignored.',
+    '',
+    'NOTE: The SAS System stopped processing this step because of errors.',
+    'WARNING: The data set WORK.CLASS may be incomplete. When this step was stopped',
+    '         there were 0 observations and 0 variables.',
+    'NOTE: DATA statement used (Total process time):',
+    '      real time           0.01 seconds',
+    '      cpu time            0.01 seconds',
+    '',
+    '6    proc print data=sashelp.class (obs=3);',
+    '7      var name age height weight;',
+    '8    run;',
+    '',
+    'NOTE: There were 3 observations read from the data set SASHELP.CLASS.',
+    'NOTE: The PROCEDURE PRINT printed page 1.',
+    'NOTE: PROCEDURE PRINT used (Total process time):',
+    '      real time           0.02 seconds',
+    '      cpu time            0.02 seconds',
+    '',
+    'NOTE: The SAS System stopped processing this step because of errors.',
+    'NOTE: SAS Institute Inc., SAS Campus Drive, Cary, NC USA 27513-2414'
+  ].join('\n'),
+  print: [
+    'The SAS System',
+    '',
+    '  Obs    Name       Age    Height    Weight',
+    '    1    Alfred      14     69.0     112.5',
+    '    2    Alice       13     56.5      84.0',
+    '    3    Barbara     13     65.3      98.0'
+  ].join('\n')
+}
 let TRANSCRIPT = null
 
 const transcript = async () => {
@@ -444,17 +506,62 @@ const logicalPath = (value) =>
     .replace(/^\/sasjs\/drive\/files/i, '')
     .replace(/\.sas$/i, '')
 
-/** The recording naming this program, if the project shipped one. */
+/** A recording with its placeholders filled in, so a demo can name what was run. */
+const withProgram = (recording, requested) => {
+  // the replacement is a function, not a string: a program path may hold `$&` or `$1`, which a
+  // string replacement expands, so a caller naming `services/$&x` would be answered with
+  // `{{program}}` in place of their own path
+  const fill = (value) =>
+    String(value || '').replaceAll(
+      '{{program}}',
+      () => requested || 'the code in this buffer'
+    )
+
+  return {
+    webout: fill(recording.webout),
+    log: fill(recording.log),
+    print: fill(recording.print)
+  }
+}
+
+/**
+ * The session this SAS run is answered with.
+ *
+ * The project's recording of that program if it shipped one, and the mocked session otherwise -
+ * never a refusal, and never nothing. A SAS run is only reached here when the host cannot
+ * execute it, which in a browser is always, so there is no case in which the honest answer is
+ * "no".
+ */
 const transcriptFor = async (programPath) => {
   const requested = logicalPath(programPath)
-  if (!requested) return undefined
-
   const recorded = await transcript()
 
-  for (const key of Object.keys(recorded))
-    if (logicalPath(key) === requested) return recorded[key]
+  if (requested)
+    for (const key of Object.keys(recorded))
+      if (logicalPath(key) === requested)
+        return withProgram(recorded[key], requested)
+
+  return withProgram(MOCKED_SESSION, requested)
+}
+
+/**
+ * Whether this request is a SAS run.
+ *
+ * A code run states its run time. A program run does not - the server resolves it against
+ * `RUN_TIMES`, which is why `R.setRunTimes` puts that order into the runtime-core resolution -
+ * and the file that comes back decides. It is the same resolution the runner makes, so the two cannot disagree about
+ * which runs are SAS: a rule of my own here would sooner or later answer a run the runner
+ * would have executed, or the reverse.
+ */
+const isSasRun = (code, runTime, program) => {
+  // a code run always states its run time - the package refuses one without it - so this is
+  // a plain comparison rather than a default
+  if (code) return String(runTime || '').toLowerCase() === 'sas'
+
+  // the request may name the program without its extension
+  const resolved = R.resolveProgram(program)
 
-  return undefined
+  return Boolean(resolved && /\.sas$/i.test(resolved))
 }
 
 /**
@@ -488,17 +595,6 @@ const recordedProgramIn = (code, runTime) => {
 }
 
 // ---------------------------------------------------------------- the runner
-/**
- * What a SAS run this host cannot answer is told.
- *
- * `sas` is one of the host's run times, so the message must not claim the run
- * time is missing: what is missing is the binary, because this is a browser. It
- * names the one thing that does answer SAS here, so a reader whose program is
- * refused knows why the demo's own program is not.
- */
-const SAS_UNAVAILABLE =
-  'SAS is not available on this host: a browser has no SAS binary, and this demo answers only the program it ships a recorded session of.'
-
 /**
  * The work a run does, over the browser's drive.
  *
@@ -518,28 +614,43 @@ class BrowserRuntime extends API.MemorySessionHost {
     const program = request.program || {}
     const params = Object.assign({}, request.vars || {})
 
-    // SAS never reaches the runner. `sas` is one of this host's run times - the
-    // recording answers the program it names - but the answer for anything else
-    // is the refusal a client already understands, not a JavaScript SyntaxError
-    // quoting the SAS source, which is what handing it to the runner would
-    // produce. The file is resolved because the request may name the program
-    // without its extension.
     const resolved =
       program.code === undefined ? R.resolveProgram(program.path) : undefined
     const isSas =
       String(request.runTime || '').toLowerCase() === 'sas' ||
       Boolean(resolved && /\.sas$/i.test(resolved))
 
-    if (isSas) throw runFailure(SAS_UNAVAILABLE)
+    // A SAS run is answered with its session, here as on the run routes: those answer before the
+    // runtime is reached, but a *trigger* goes through it, and a mock must not be the one place
+    // that refuses a run for want of a binary it never had. Handing SAS source to the JavaScript
+    // runner would be worse still - a SyntaxError quoting the source.
+    let artifact
+    if (isSas) {
+      const recording = await transcriptFor(
+        program.code !== undefined
+          ? recordedProgramIn(program.code, request.runTime)
+          : program.path
+      )
 
-    const payload = { params, tables: tablesOf(request.files) }
-    if (program.code !== undefined) payload.code = program.code
-    else payload.program = program.path
+      artifact = artifactOf(
+        {
+          webout: recording.webout || '',
+          log: recording.log || '',
+          print: recording.print || '',
+          headers: SEEDED_HEADER_LINE
+        },
+        params._debug !== undefined
+      )
+    } else {
+      const payload = { params, tables: tablesOf(request.files) }
+      if (program.code !== undefined) payload.code = program.code
+      else payload.program = program.path
 
-    const result = R.run(payload)
-    if (result.error) throw runFailure(result.error)
+      const result = R.run(payload)
+      if (result.error) throw runFailure(result.error)
 
-    const artifact = artifactOf(result, params._debug !== undefined)
+      artifact = artifactOf(result, params._debug !== undefined)
+    }
     const session = request.session
     if (session) {
       const stamp = new Date().toISOString()
@@ -625,21 +736,26 @@ const withoutBase = (pathname) =>
 
 // ------------------------------------------------------------- what it can run
 /**
- * The run times this host answers, in the order a client should try them.
+ * The run times this host answers, in order of priority.
  *
- * `js` is executed here, in the page's own JavaScript engine. `sas` is answered
- * from the recorded session (`host/sas-transcript.json`) for the one program the
- * recording names; any other SAS program is refused by `SAS_UNAVAILABLE`, which
- * names the missing binary rather than a missing run time - a browser has none.
+ * `js` is executed here, in the page's own JavaScript engine. `sas` is answered from a session -
+ * the project's recording of that program (`host/sas-transcript.json`) when it ships one, and the
+ * mocked session otherwise. That holds on every route that runs one: a run, a code run, and a
+ * trigger, which reaches the runtime rather than the run route and is answered there.
  *
- * Both the `/SASjsApi/info` answer and the runtime service read this list, so the
- * run times the host states and the ones its service accepts cannot drift apart.
- * `sas` is stated because that is what offers Run on a `.sas` file at all; a
- * program the recording does not name is then refused with its reason, not by the
- * run time being absent from a list the host publishes.
+ * The order is the priority SASjs Server gives `RUN_TIMES` (`docs/pages/settings.md`): `js` leads
+ * here, because a browser executes JavaScript and holds a recording where a server has a binary.
+ * Everything else is derived from this list - the order an extension-less program is resolved in
+ * (`R.setRunTimes` below), and what `/SASjsApi/info` and the runtime service report, so the run
+ * times the host publishes and the ones its service accepts cannot drift apart. `sas` is stated
+ * because that is what offers Run on a `.sas` file at all.
  */
 const RUN_TIMES = ['js', 'sas']
 
+// the order decides which program an extension-less reference runs, the way the server's
+// RUN_TIMES does - `services/x` is `x.js` here, because `js` comes first
+R.setRunTimes(RUN_TIMES)
+
 // ------------------------------------------------------------- host reports
 // The Admin routes ask a host what it is doing. A browser has no process, but it
 // does have a page, a heap and this worker's own activity, so the reports are
@@ -1211,36 +1327,34 @@ const runRoute = async (routeId, payload, subject) => {
     runRequest.program = query._program || body._program
   }
 
-  // A recorded SAS session is answered here, ahead of the run. `sas` IS one of
-  // this host's run times - it is what the Studio reads to offer Run on a .sas
-  // file - and the recording is how it is answered, so the check comes before
-  // the package would compile the source as JavaScript. A trigger is excluded:
-  // it has to answer with the session record the route builds, which a client
-  // parses as JSON, so a recording is not an answer there.
-  if (!trigger) {
-    const recorded = code
-      ? recordedProgramIn(body.code, body.runTime)
-      : runRequest.program
-    const recording = recorded ? await transcriptFor(recorded) : undefined
-
-    if (recording)
-      return artifactResponse(
-        artifactOf(
-          {
-            webout: recording.webout || '',
-            log: recording.log || '',
-            print: recording.print || '',
-            // the seed every session starts with, so a run without `_debug`
-            // answers text/html rather than leaving the type to the browser -
-            // the same rule runtime-core applies to a service that declares none
-            headers: SEEDED_HEADER_LINE
-          },
-          // a code run carries no `_debug` and still answers with its log: the
-          // package compiles a code run at its own debug level, and the Studio
-          // splits the three parts on the separator it writes
-          code ? true : vars._debug !== undefined
-        )
+  // A SAS run is answered here, ahead of the run: this host cannot execute one, so the answer
+  // is a session - the project's recording of that program, or the mocked one. `sas` IS one of
+  // this host's run times, which is what the Studio reads to offer Run on a `.sas` file, so the
+  // check comes before the package would compile the source as JavaScript. A trigger is
+  // excluded: it has to answer with the session record the route builds, which a client parses
+  // as JSON, so a transcript is not an answer there.
+  if (!trigger && isSasRun(code, body.runTime, runRequest.program)) {
+    const recording = await transcriptFor(
+      code ? recordedProgramIn(body.code, body.runTime) : runRequest.program
+    )
+
+    return artifactResponse(
+      artifactOf(
+        {
+          webout: recording.webout || '',
+          log: recording.log || '',
+          print: recording.print || '',
+          // the seed every session starts with, so a run without `_debug`
+          // answers text/html rather than leaving the type to the browser -
+          // the same rule runtime-core applies to a service that declares none
+          headers: SEEDED_HEADER_LINE
+        },
+        // a code run carries no `_debug` and still answers with its log: the
+        // package compiles a code run at its own debug level, and the Studio
+        // splits the three parts on the separator it writes
+        code ? true : vars._debug !== undefined
       )
+    )
   }
 
   if (trigger) {

package/build/commands/build/internal/mockSite/spec/intercept.spec.js

@@ -275,6 +275,66 @@ describe('page-side bridge', function () {
             }
         });
     }); });
+    it('hands a blob request the bytes, not the body decoded as text', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var bytes, XHR, xhr, readBack, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    bytes = new Uint8Array([
+                        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d
+                    ]);
+                    XHR = loadBridge(jest.fn(function () { return __awaiter(void 0, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            return [2 /*return*/, new Response(bytes, {
+                                    status: 200,
+                                    headers: { 'content-type': 'image/png' }
+                                })];
+                        });
+                    }); })).XHR;
+                    xhr = new XHR();
+                    xhr.responseType = 'blob';
+                    return [4 /*yield*/, run(xhr, 'GET', '/SASjsApi/drive/file?_filePath=%2FPublic%2Fapp%2Fmacrodash%2Fservices%2Fweb%2Fmacrodash.png')];
+                case 1:
+                    _b.sent();
+                    expect(xhr.status).toBe(200);
+                    expect(xhr.response).toBeInstanceOf(Blob);
+                    expect(xhr.response.type).toBe('image/png');
+                    expect(xhr.response.size).toBe(bytes.length);
+                    expect(xhr.responseText).toBe('');
+                    _a = Uint8Array.bind;
+                    return [4 /*yield*/, xhr.response.arrayBuffer()];
+                case 2:
+                    readBack = new (_a.apply(Uint8Array, [void 0, _b.sent()]))();
+                    expect(Array.from(readBack)).toEqual(Array.from(bytes));
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    it('hands an arraybuffer request the bytes as well', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var bytes, XHR, xhr;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    bytes = new Uint8Array([1, 2, 3, 4]);
+                    XHR = loadBridge(jest.fn(function () { return __awaiter(void 0, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            return [2 /*return*/, new Response(bytes, {
+                                    status: 200,
+                                    headers: { 'content-type': 'application/octet-stream' }
+                                })];
+                        });
+                    }); })).XHR;
+                    xhr = new XHR();
+                    xhr.responseType = 'arraybuffer';
+                    return [4 /*yield*/, run(xhr, 'GET', '/SASjsApi/drive/file?_filePath=%2Fx.bin')];
+                case 1:
+                    _a.sent();
+                    expect(Array.from(new Uint8Array(xhr.response))).toEqual([1, 2, 3, 4]);
+                    expect(xhr.responseText).toBe('');
+                    return [2 /*return*/];
+            }
+        });
+    }); });
     it('answers with a 500 body when the request itself fails', function () { return __awaiter(void 0, void 0, void 0, function () {
         var consoleError, XHR, xhr;
         return __generator(this, function (_a) {

package/build/commands/build/internal/mockSite/spec/runtime-core.spec.js

@@ -58,7 +58,12 @@ var loadRuntime = function () {
     ;
     global.self = {};
     jest.resetModules();
-    return require('../assets/runtime-core.js');
+    var runtime = require('../assets/runtime-core.js');
+    // the host declares its run times, and the site's worker does the same from its own
+    // `RUN_TIMES` (sw.js): an extension-less program is resolved in that order, so a runtime
+    // driven without a declaration resolves exact paths only
+    runtime.setRunTimes(['js', 'sas']);
+    return runtime;
 };
 var jsonResponse = function (body) { return ({
     ok: true,