@sasjs/cli 6.10.0 → 6.11.0

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

@@ -954,6 +954,35 @@ const resolveProgram = (program) => {
   return null
 }
 
+/**
+ * The header file a session starts with. sasjs/server seeds this exact line
+ * into a JS session (controllers/internal/Session.ts), so a service that
+ * declares no type answers text/html rather than leaving the choice to the
+ * browser - a mock build matches that here.
+ *
+ * The trailing newline is part of it: the server writes it for a JS session
+ * (`'content-type: text/html; charset=utf-8\n'` in Session.ts, as against the
+ * SAS 9 session's seed with no newline), and it is what keeps a service that
+ * appends a header without a leading newline on its own line - otherwise the two
+ * concatenate into one unusable value.
+ *
+ * It is a default, not a declaration: the worker ignores it for a byte body,
+ * so a service that writes bytes and names no type is still an undeclared
+ * download rather than being labelled text/html. The worker reads the value
+ * from HEADERS_SEED below, so the seed and the rule cannot drift.
+ */
+const SEEDED_HEADERS = 'content-type: text/html; charset=utf-8\n'
+
+/**
+ * The largest body a single upload may carry.
+ *
+ * A browser worker holds the whole payload in memory, so an oversized upload is
+ * an out-of-memory failure rather than a limit a client can act on. This is the
+ * same 10 MB a deploy allows for one file, and it is checked from the File's
+ * `size` before the body is read.
+ */
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024
+
 const runProgram = ({ program, code, params = {}, tables = [] }) => {
   const payloadCode = code
   const codePath = program ? resolveProgram(program) : null
@@ -977,7 +1006,7 @@ const runProgram = ({ program, code, params = {}, tables = [] }) => {
   const headersPath = `${sessionDir}/stpsrv_header.txt`
   const tokenFile = `${sessionDir}/reqHeaders.txt`
   FILES.set(weboutPath, '')
-  FILES.set(headersPath, '')
+  FILES.set(headersPath, SEEDED_HEADERS)
   FILES.set(tokenFile, '')
 
   const varStatements = Object.entries(params)
@@ -1144,7 +1173,9 @@ const readDriveFile = (filePath) => {
     String(filePath).replace(/^\/+/, '')
   )
   if (!FILES.has(abs)) {
-    const err = new Error('File not found')
+    // the server's wording, because a client prints this: GET /drive/file
+    // answers `res.status(404).send(err.message)`
+    const err = new Error(`File doesn't exist.`)
     err.status = 404
     throw err
   }
@@ -1160,6 +1191,207 @@ const readDriveFile = (filePath) => {
 /** The stored base64 of a byte entry, once it is known to decode. */
 const validateEntry = (contents) => cleanedBase64(contents)
 
+// ------------------------------------------------------------- drive writes
+// The /drive endpoints answer the same contract sasjs/server serves, so a client
+// that uploads, renames or deletes needs no change for a mock build - only the
+// storage differs (a Map here, a folder on the server). Every mutation marks the
+// entry dirty, which is how the page learns to persist it: the worker can be
+// terminated between requests, so a write it did not hand back would live only
+// until the next reload.
+
+const DRIVE_FILES = () => `${DRIVE_ROOT}/files`
+
+const driveError = (status, message) => {
+  const error = new Error(message)
+  error.status = status
+  return error
+}
+
+/**
+ * A caller-supplied path as the absolute path under the drive root, or null when
+ * it lands outside - the rule sasjs/server applies in resolveWithinDrive. A
+ * leading slash means "under the drive root", never filesystem absolute, and the
+ * test is on the whole normalised path rather than a substring: `/drive/filesx`
+ * is not inside `/drive/files`.
+ */
+const drivePath = (unsafePath) => {
+  const root = DRIVE_FILES()
+  const normalised = String(
+    unsafePath === undefined || unsafePath === null ? '' : unsafePath
+  )
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+  const resolved = P.resolve(root, normalised)
+  return resolved === root || resolved.startsWith(root + '/') ? resolved : null
+}
+
+/**
+ * Writes one entry: bytes stay bytes (behind the base64 marker the drive reads
+ * them back from), a string is text, and the entry is marked for persistence.
+ *
+ * An upload arrives as bytes and is stored as bytes, which is also what the
+ * server does: multer writes the request body to disk and `saveFile` moves that
+ * file, so an uploaded CSV is a byte file there too - a program reading it
+ * without an encoding gets a Buffer on both hosts, and with `'utf8'` a string.
+ * The difference a client actually sees is the content type a download is served
+ * with, and that is decided by the extension on the GET route, as `sendFile`
+ * does on the server.
+ */
+const storeEntry = (abs, data) => {
+  const bytes = asBytes(data)
+  FILES.set(
+    abs,
+    bytes
+      ? BINARY_PREFIX + bytesToBase64(bytes)
+      : encodeText(String(data === undefined || data === null ? '' : data))
+  )
+  SIZES.delete(abs)
+  markDirty(abs)
+}
+
+/**
+ * The ancestor of a path that is itself a file, if there is one. `mkdirp` would
+ * happily turn `/data/x.csv` into a folder to hold `/data/x.csv/child`, leaving a
+ * path that is a file and has children at the same time - a state the server
+ * never reaches, because the filesystem refuses it (ENOTDIR).
+ */
+const fileAncestorOf = (abs) => {
+  const parts = abs.split('/').filter(Boolean)
+  let acc = ''
+  for (const part of parts.slice(0, -1)) {
+    acc += '/' + part
+    if (FILES.has(acc)) return acc
+  }
+  return null
+}
+
+const saveDriveFile = (filePath, data) => {
+  const abs = drivePath(filePath)
+  if (!abs || abs === DRIVE_FILES())
+    throw driveError(400, `Can't put file outside drive.`)
+  // a folder at the same path would leave one path present as both, which the
+  // server fails at the filesystem (EISDIR) rather than reporting as a conflict
+  if (FILES.has(abs) || DIRS.has(abs))
+    throw driveError(409, 'File already exists.')
+  // the server fails this at the filesystem with ENOTDIR and answers a 500; a
+  // named refusal is more use to a client than reproducing that, so it is a 400
+  const ancestor = fileAncestorOf(abs)
+  if (ancestor)
+    // the drive-relative path, never the host's absolute one: a client has no
+    // business knowing where the drive lives
+    throw driveError(
+      400,
+      `An ancestor of the path is a file: ${ancestor.slice(DRIVE_FILES().length) || '/'}`
+    )
+  mkdirp(P.dirname(abs))
+  storeEntry(abs, data)
+  return { status: 'success' }
+}
+
+const updateDriveFile = (filePath, data) => {
+  const abs = drivePath(filePath)
+  if (!abs || abs === DRIVE_FILES())
+    throw driveError(400, `Can't modify file outside drive.`)
+  if (!FILES.has(abs)) throw driveError(404, `File doesn't exist.`)
+  storeEntry(abs, data)
+  return { status: 'success' }
+}
+
+const removeDriveFile = (filePath) => {
+  const abs = drivePath(filePath)
+  if (!abs || abs === DRIVE_FILES())
+    throw driveError(400, `Can't delete file outside drive.`)
+  if (!FILES.has(abs)) throw driveError(404, `File doesn't exist.`)
+  FILES.delete(abs)
+  SIZES.delete(abs)
+  markDirty(abs)
+  return { status: 'success' }
+}
+
+const addDriveFolder = (folderPath) => {
+  const abs = drivePath(folderPath)
+  if (!abs || abs === DRIVE_FILES())
+    throw driveError(400, `Can't put folder outside drive.`)
+  if (DIRS.has(abs) || FILES.has(abs))
+    throw driveError(409, 'Folder already exists.')
+  mkdirp(abs)
+  return { status: 'success' }
+}
+
+/**
+ * Deletes a folder and everything under it. The drive is a flat map of paths, so
+ * this is the entries' prefix rather than a directory walk - and each file it
+ * removes is marked dirty (as a deletion) so the page drops it from IndexedDB
+ * too. An empty folder is not represented in the persisted drive, which is a
+ * map of files; see the note on the docs page.
+ */
+const removeDriveFolder = (folderPath) => {
+  const abs = drivePath(folderPath)
+  if (!abs || abs === DRIVE_FILES())
+    throw driveError(400, `Can't delete folder outside drive.`)
+  if (!DIRS.has(abs)) throw driveError(404, `Folder doesn't exist.`)
+  const prefix = abs + '/'
+  for (const path of [...FILES.keys()]) {
+    if (!path.startsWith(prefix)) continue
+    FILES.delete(path)
+    SIZES.delete(path)
+    markDirty(path)
+  }
+  for (const dir of [...DIRS]) {
+    if (dir === abs || dir.startsWith(prefix)) DIRS.delete(dir)
+  }
+  return { status: 'success' }
+}
+
+/** Moves one stored file, leaving both paths for the page to persist. */
+const moveEntry = (from, to) => {
+  FILES.set(to, FILES.get(from))
+  FILES.delete(from)
+  SIZES.delete(from)
+  SIZES.delete(to)
+  markDirty(to)
+  markDirty(from)
+}
+
+const renameDriveEntry = (oldPath, newPath) => {
+  const from = drivePath(oldPath)
+  if (!from || from === DRIVE_FILES())
+    throw driveError(400, `Old path can't be outside of drive.`)
+  const to = drivePath(newPath)
+  if (!to || to === DRIVE_FILES())
+    throw driveError(400, `New path can't be outside of drive.`)
+
+  if (DIRS.has(from)) {
+    // the server fails this at the filesystem; naming it here says why
+    if (to.startsWith(from + '/'))
+      throw driveError(400, `New path can't be inside the folder being moved.`)
+    if (DIRS.has(to) || FILES.has(to))
+      throw driveError(409, 'Folder with new name already exists.')
+    const prefix = from + '/'
+    mkdirp(P.dirname(to))
+    for (const dir of [...DIRS]) {
+      if (dir === from || dir.startsWith(prefix)) {
+        DIRS.delete(dir)
+        mkdirp(to + dir.slice(from.length))
+      }
+    }
+    for (const path of [...FILES.keys()]) {
+      if (path.startsWith(prefix)) moveEntry(path, to + path.slice(from.length))
+    }
+    return { status: 'success' }
+  }
+
+  if (FILES.has(from)) {
+    if (FILES.has(to) || DIRS.has(to))
+      throw driveError(409, 'File with new name already exists.')
+    mkdirp(P.dirname(to))
+    moveEntry(from, to)
+    return { status: 'success' }
+  }
+
+  throw driveError(404, 'No file/folder found for provided path.')
+}
+
 const buildTree = () => {
   const walk = (dir) => {
     const node = {
@@ -1337,7 +1569,21 @@ const api = {
   run: (payload) => runProgram(payload),
   list: (folder) => listFolder(folder),
   read: (file) => readDriveFile(file),
+  // the write half of the drive API: each one answers the server's success body
+  // or throws an error carrying the server's status and message
+  save: (filePath, data) => saveDriveFile(filePath, data),
+  update: (filePath, data) => updateDriveFile(filePath, data),
+  remove: (filePath) => removeDriveFile(filePath),
+  mkdir: (folderPath) => addDriveFolder(folderPath),
+  rmdir: (folderPath) => removeDriveFolder(folderPath),
+  rename: (oldPath, newPath) => renameDriveEntry(oldPath, newPath),
   tree: () => buildTree(),
+  // the content type a session's header file is seeded with, so the worker can
+  // tell a default from a declaration rather than carrying a second literal
+  HEADERS_SEED: SEEDED_HEADERS,
+  // the largest single upload the host accepts, so the worker can refuse a body
+  // before materialising it and the specs and docs read the same number
+  MAX_UPLOAD_BYTES: MAX_UPLOAD_BYTES,
   // the format the snapshot download stamps, so persist.js writes the number
   // this runtime reads rather than a second literal
   DRIVE_FORMAT

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

@@ -11,12 +11,13 @@
  * receives the changed files back after every run.
  *
  * TRUST MODEL: this is a single-user, no-auth host. It answers every /SASjsApi/
- * path on the site's origin, runs whatever program the request names, and runs
- * the code a code/execute request carries - the same contract a SASjs server
- * offers, minus the server. Nothing here is a boundary: a page at this origin
- * can already do all of it, because a visitor's own browser is the client. So
- * a site holding anything private, or one served from a shared origin, belongs
- * behind a real server rather than a static host.
+ * path on the site's origin, writes to the drive when a drive request names a
+ * path, runs whatever program the request names, and runs the code a
+ * code/execute request carries - the same contract a SASjs server offers, minus
+ * the server. Nothing here is a boundary: a page at this origin can already do
+ * all of it, because a visitor's own browser is the client. So a site holding
+ * anything private, or one served from a shared origin, belongs behind a real
+ * server rather than a static host.
  */
 importScripts('/host/runtime-core.js')
 
@@ -101,6 +102,14 @@ const parseHeaders = (content) => {
   return headers
 }
 
+/**
+ * The content type a session's header file is seeded with - the server's
+ * default, not something the service asked for. The runtime owns the seed line,
+ * so the value is taken from it rather than repeated here: a byte body that
+ * carries only this type is an undeclared download, not a text/html one.
+ */
+const SEEDED_HEADERS = String(R.HEADERS_SEED)
+
 /**
  * The reply a run produces: the webout, in the shape and under the name the
  * service asked for. A debug reply is the webout framed with the log, so it
@@ -114,6 +123,12 @@ const weboutResponse = (result, debug) => {
 
   const headers = parseHeaders(result.headers)
   if (result.binary) {
+    // the seed is a default, so a byte body that leaves the seeded file untouched
+    // declares nothing: it keeps the type an undeclared download gets. Compared as
+    // the raw text rather than as the parsed value, so a service that declares
+    // this same content type itself keeps it - only the untouched seed is dropped.
+    if (String(result.headers) === SEEDED_HEADERS)
+      delete headers['content-type']
     if (!headers['content-type'])
       headers['content-type'] = 'application/octet-stream'
     return new Response(toBytes(result.webout), { status: 200, headers })
@@ -159,6 +174,123 @@ const readPayload = async (request) => {
   return { params: body.params || {}, tables: body.tables || [], json: body }
 }
 
+// ---------------------------------------------------------------- requests
+/** A request body as JSON, and {} when it is not JSON - a client that posts a
+ * form where the route wants JSON gets the missing-field answer rather than a
+ * parse error. */
+const readJson = async (request) => {
+  try {
+    return (await request.json()) || {}
+  } catch (e) {
+    return {}
+  }
+}
+
+const badRequest = (message) => {
+  const error = new Error(message)
+  error.status = 400
+  return error
+}
+
+const payloadTooLarge = (limit) => {
+  const error = new Error(
+    `The upload is larger than the browser host allows (${Math.round(
+      limit / (1024 * 1024)
+    )} MB).`
+  )
+  error.status = 413
+  return error
+}
+
+/**
+ * The value a route needs, or the 400 the server answers with when it is absent.
+ * The message is Joi's, because that is what a client sees from the real API.
+ */
+const required = (value, name) => {
+  if (typeof value === 'string' && value.length) return value
+  throw badRequest(`"${name}" is required`)
+}
+
+/**
+ * sasjs/server refuses a file path with one of these extensions (filePathSchema
+ * in api/src/utils/validation.ts). Nothing is executable on a static host, but a
+ * client that would be refused on deploy should hear it here too.
+ */
+const BLOCKED_FILE = /\.(exe|sh|htaccess)$/i
+
+const fileTarget = (value, name) => {
+  const given = required(value, name)
+  if (BLOCKED_FILE.test(given)) throw badRequest('Invalid file extension')
+  return given
+}
+
+/** The bytes of an uploaded file, from the multipart field the API names. */
+const uploadBytes = async (request) => {
+  const form = await request.formData().catch(() => null)
+  const upload = form && form.get('file')
+  if (!upload || typeof upload === 'string')
+    throw badRequest('"file" is not present.')
+  // refused from the File's size, before the body is read: a worker holds the
+  // whole payload in memory, so an oversized upload there is an out-of-memory
+  // failure rather than an answer a client can act on
+  if (typeof upload.size === 'number' && upload.size > R.MAX_UPLOAD_BYTES)
+    throw payloadTooLarge(R.MAX_UPLOAD_BYTES)
+  const target = form.get('filePath')
+  return {
+    bytes: new Uint8Array(await upload.arrayBuffer()),
+    filePath: target === null ? undefined : target
+  }
+}
+
+/**
+ * The content type `sendFile` would answer with for this path - by extension,
+ * because that is what express does, and because a byte entry would otherwise be
+ * served as `application/octet-stream` however text-like it is.
+ */
+const CONTENT_TYPES = {
+  '.csv': 'text/csv',
+  '.json': 'application/json',
+  '.sas': 'text/plain',
+  '.txt': 'text/plain',
+  '.log': 'text/plain',
+  '.html': 'text/html',
+  '.htm': 'text/html',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.zip': 'application/zip',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.xls': 'application/vnd.ms-excel',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml'
+}
+
+const contentTypeFor = (filePath, binary) => {
+  const name = String(filePath || '').toLowerCase()
+  const dot = name.lastIndexOf('.')
+  const known = dot > 0 ? CONTENT_TYPES[name.slice(dot)] : undefined
+  if (known) return known
+  return binary ? 'application/octet-stream' : 'text/plain'
+}
+
+/**
+ * Runs one drive mutation and then hands the page the entries it changed. The
+ * worker can be terminated between requests, so a write is only durable once the
+ * page has put it in IndexedDB.
+ *
+ * Await it at the call site: a bare `return driveResponse(...)` hands the
+ * promise back through handle's try without running its catch, so a refused
+ * write would reach the page as an unhandled rejection instead of its status.
+ */
+const driveResponse = async (runner) => {
+  const result = runner()
+  await persistChanges()
+  return json(result)
+}
+
 const handle = async (request, url) => {
   const path = url.pathname.replace(/\/+$/, '')
   const query = {}
@@ -178,20 +310,77 @@ const handle = async (request, url) => {
     }
 
     if (path.endsWith('/SASjsApi/drive/folder')) {
-      return json(await R.list(query._folderPath || ''))
+      if (request.method === 'GET')
+        return json(await R.list(query._folderPath || ''))
+
+      if (request.method === 'POST') {
+        const body = await readJson(request)
+        return await driveResponse(() =>
+          R.mkdir(required(body.folderPath, 'folderPath'))
+        )
+      }
+
+      if (request.method === 'DELETE') {
+        // an empty path names the drive root, which the server refuses at
+        // validation rather than deleting everything
+        const folderPath = required(query._folderPath, '_folderPath')
+        return await driveResponse(() => R.rmdir(folderPath))
+      }
     }
 
     if (path.endsWith('/SASjsApi/drive/filetree')) {
       return json(R.tree())
     }
 
-    if (path.endsWith('/SASjsApi/drive/file') && request.method === 'GET') {
-      const file = R.read(query._filePath || '')
-      return file.binary
-        ? new Response(toBytes(file.contents), {
-            headers: { 'content-type': 'application/octet-stream' }
-          })
-        : text(file.contents)
+    if (path.endsWith('/SASjsApi/drive/rename')) {
+      if (request.method === 'POST') {
+        const body = await readJson(request)
+        // both ends go through the extension check: without it a file could be
+        // renamed into a blocked name and then be unreachable by DELETE and PATCH,
+        // which apply the same check to the path they are given
+        const oldPath = fileTarget(body.oldPath, 'oldPath')
+        const newPath = fileTarget(body.newPath, 'newPath')
+        return await driveResponse(() => R.rename(oldPath, newPath))
+      }
+    }
+
+    if (path.endsWith('/SASjsApi/drive/file')) {
+      if (request.method === 'GET') {
+        const file = R.read(query._filePath || '')
+        // the server answers this with `sendFile`, so the type comes from the
+        // extension: a .csv is text/csv whether it was uploaded as bytes or
+        // written by a service as text
+        return new Response(
+          file.binary ? toBytes(file.contents) : file.contents,
+          {
+            status: 200,
+            headers: {
+              'content-type': contentTypeFor(query._filePath, file.binary)
+            }
+          }
+        )
+      }
+
+      if (request.method === 'DELETE') {
+        const filePath = fileTarget(query._filePath, '_filePath')
+        return await driveResponse(() => R.remove(filePath))
+      }
+
+      // POST creates (409 when the path is taken) and PATCH replaces (404 when
+      // it is not there) - the split the server's routes make, so a client that
+      // keys on the status code behaves the same way
+      if (request.method === 'POST' || request.method === 'PATCH') {
+        const upload = await uploadBytes(request)
+        const filePath = fileTarget(
+          query._filePath || upload.filePath,
+          '_filePath'
+        )
+        return await driveResponse(() =>
+          request.method === 'PATCH'
+            ? R.update(filePath, upload.bytes)
+            : R.save(filePath, upload.bytes)
+        )
+      }
     }
 
     if (
@@ -238,6 +427,12 @@ const handle = async (request, url) => {
   } catch (e) {
     const message = (e && e.stack) || String(e)
     broadcast({ type: 'sasjs-host-error', path, message })
+    // A drive refusal is the message itself, in plain text: the server answers
+    // these with `res.status(code).send(err.message)`, and its own suite asserts
+    // `res.text`. The other routes answer JSON, because a program failure
+    // carries more than a message (`status`, `error`), so they keep the envelope.
+    if (path.includes('/SASjsApi/drive/') && e && e.status)
+      return text((e && e.message) || String(e), e.status)
     return json(
       { message: (e && e.message) || String(e) },
       (e && e.status) || 500