build: axios package dependency changes. Missing type added in Group.ts

## [0.39.1](https://github.com/sasjs/server/compare/v0.39.0...v0.39.1) (2025-03-13)

### Bug Fixes

* extra bit of sleep for file recognition ([f4768bf](f4768bffd3)), closes [#381](https://github.com/sasjs/server/issues/381)

.github/workflows/build.yml

@@ -5,7 +5,7 @@ on:
 
 jobs:
   lint:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
 
     strategy:
       matrix:
@@ -28,7 +28,7 @@ jobs:
         run: npm run lint-web
 
   build-api:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
 
     strategy:
       matrix:
@@ -66,7 +66,7 @@ jobs:
           CI: true
 
   build-web:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
 
     strategy:
       matrix:

.vscode/settings.json

@@ -1,5 +1,3 @@
 {
-  "cSpell.words": [
-    "autoexec"
-  ]
+  "cSpell.words": ["autoexec", "initialising"]
 }

CHANGELOG.md

@@ -1,3 +1,57 @@
+## [0.39.1](https://github.com/sasjs/server/compare/v0.39.0...v0.39.1) (2025-03-13)
+
+
+### Bug Fixes
+
+* extra bit of sleep for file recognition ([f4768bf](https://github.com/sasjs/server/commit/f4768bffd3dbb2fe243966572ba74002024d96e1)), closes [#381](https://github.com/sasjs/server/issues/381)
+
+# [0.39.0](https://github.com/sasjs/server/compare/v0.38.0...v0.39.0) (2024-10-31)
+
+
+### Bug Fixes
+
+* **api:** fixed condition in processProgram ([48a9a4d](https://github.com/sasjs/server/commit/48a9a4dd0e31f84209635382be4ec4bb2c3a9c0c))
+
+
+### Features
+
+* **api:** added session state endpoint ([6b6546c](https://github.com/sasjs/server/commit/6b6546c7ad0833347f8dc4cdba6ad19132f7aaef))
+
+# [0.38.0](https://github.com/sasjs/server/compare/v0.37.0...v0.38.0) (2024-10-30)
+
+
+### Features
+
+* **api:** enabled query params in stp/trigger endpoint ([5cda9cd](https://github.com/sasjs/server/commit/5cda9cd5d8623b7ea2ecd989d7808f47ec866672))
+
+# [0.37.0](https://github.com/sasjs/server/compare/v0.36.0...v0.37.0) (2024-10-29)
+
+
+### Features
+
+* **stp:** added trigger endpoint ([b0723f1](https://github.com/sasjs/server/commit/b0723f14448d60ffce4f2175cf8a73fc4d4dd0ee))
+
+# [0.36.0](https://github.com/sasjs/server/compare/v0.35.4...v0.36.0) (2024-10-29)
+
+
+### Features
+
+* **code:** added code/trigger API endpoint ([ffcf193](https://github.com/sasjs/server/commit/ffcf193b87d811b166d79af74013776a253b50b0))
+
+## [0.35.4](https://github.com/sasjs/server/compare/v0.35.3...v0.35.4) (2024-01-15)
+
+
+### Bug Fixes
+
+* **api:** fixed env issue in MacOS executable ([73d965d](https://github.com/sasjs/server/commit/73d965daf54b16c0921e4b18d11a1e6f8650884d))
+
+## [0.35.3](https://github.com/sasjs/server/compare/v0.35.2...v0.35.3) (2023-11-07)
+
+
+### Bug Fixes
+
+* enable embedded LFs in JS STP vars ([7e8cbbf](https://github.com/sasjs/server/commit/7e8cbbf377b27a7f5dd9af0bc6605c01f302f5d9))
+
 ## [0.35.2](https://github.com/sasjs/server/compare/v0.35.1...v0.35.2) (2023-08-07)
 
 

api/.env.example

@@ -25,7 +25,7 @@ LDAP_USERS_BASE_DN = <ou=users,dc=cloudron>
 LDAP_GROUPS_BASE_DN = <ou=groups,dc=cloudron>
 
 #default value is 100
-MAX_WRONG_ATTEMPTS_BY_IP_PER_DAY=100 
+MAX_WRONG_ATTEMPTS_BY_IP_PER_DAY=100
 
 #default value is 10
 MAX_CONSECUTIVE_FAILS_BY_USERNAME_AND_IP=10

api/package.json

@@ -18,10 +18,10 @@
     "lint": "npx prettier --check \"src/**/*.{ts,tsx,js,jsx,html,css,sass,less,yml,md,graphql}\"",
     "exe": "npm run build && pkg .",
     "copy:files": "npm run public:copy && npm run sasjsbuild:copy && npm run sas:copy && npm run web:copy",
-    "public:copy": "cpr ./public/ ./build/public/",
-    "sasjsbuild:copy": "cpr ./sasjsbuild/ ./build/sasjsbuild/",
-    "sas:copy": "cpr ./sas/ ./build/sas/",
-    "web:copy": "rimraf web && mkdir web && cpr ../web/build/ ./web/build/",
+    "public:copy": "cp -r ./public/ ./build/public/",
+    "sasjsbuild:copy": "cp -r ./sasjsbuild/ ./build/sasjsbuild/",
+    "sas:copy": "cp -r ./sas/ ./build/sas/",
+    "web:copy": "rimraf web && mkdir web && cp -r ../web/build/ ./web/build/",
     "compileSysInit": "ts-node ./scripts/compileSysInit.ts",
     "copySASjsCore": "ts-node ./scripts/copySASjsCore.ts",
     "downloadMacros": "ts-node ./scripts/downloadMacros.ts"
@@ -86,17 +86,16 @@
     "@types/swagger-ui-express": "^4.1.3",
     "@types/unzipper": "^0.10.5",
     "adm-zip": "^0.5.9",
-    "axios": "0.27.2",
-    "cpr": "^3.0.1",
+    "axios": "^1.12.2",
     "csrf": "^3.1.0",
-    "dotenv": "^10.0.0",
+    "dotenv": "^16.0.1",
     "http-headers-validation": "^0.0.1",
     "jest": "^27.0.6",
     "mongodb-memory-server": "8.11.4",
     "nodejs-file-downloader": "4.10.2",
     "nodemon": "^2.0.7",
     "pkg": "5.6.0",
-    "prettier": "^3.0.3",
+    "prettier": "^2.3.1",
     "rimraf": "^3.0.2",
     "supertest": "^6.1.3",
     "ts-jest": "^27.0.3",

api/public/swagger.yaml

@@ -98,17 +98,47 @@ components:
             properties:
                 code:
                     type: string
-                    description: 'Code of program'
-                    example: '* Code HERE;'
+                    description: 'The code to be executed'
+                    example: '* Your Code HERE;'
                 runTime:
                     $ref: '#/components/schemas/RunTimeType'
-                    description: 'runtime for program'
+                    description: 'The runtime for the code - eg SAS, JS, PY or R'
                     example: js
             required:
                 - code
                 - runTime
             type: object
             additionalProperties: false
+        TriggerCodeResponse:
+            properties:
+                sessionId:
+                    type: string
+                    description: "`sessionId` is the ID of the session and the name of the temporary folder\nused to store code outputs.<br><br>\nFor SAS, this would be the location of the SASWORK folder.<br><br>\n`sessionId` can be used to poll session state using the\nGET /SASjsApi/session/{sessionId}/state endpoint."
+                    example: 20241028074744-54132-1730101664824
+            required:
+                - sessionId
+            type: object
+            additionalProperties: false
+        TriggerCodePayload:
+            properties:
+                code:
+                    type: string
+                    description: 'The code to be executed'
+                    example: '* Your Code HERE;'
+                runTime:
+                    $ref: '#/components/schemas/RunTimeType'
+                    description: 'The runtime for the code - eg SAS, JS, PY or R'
+                    example: sas
+                expiresAfterMins:
+                    type: number
+                    format: double
+                    description: "Amount of minutes after the completion of the job when the session must be\ndestroyed."
+                    example: 15
+            required:
+                - code
+                - runTime
+            type: object
+            additionalProperties: false
         MemberType.folder:
             enum:
                 - folder
@@ -555,6 +585,14 @@ components:
                 - needsToUpdatePassword
             type: object
             additionalProperties: false
+        SessionState:
+            enum:
+                - initialising
+                - pending
+                - running
+                - completed
+                - failed
+            type: string
         ExecutePostRequestPayload:
             properties:
                 _program:
@@ -563,6 +601,16 @@ components:
                     example: /Public/somefolder/some.file
             type: object
             additionalProperties: false
+        TriggerProgramResponse:
+            properties:
+                sessionId:
+                    type: string
+                    description: "`sessionId` is the ID of the session and the name of the temporary folder\nused to store program outputs.<br><br>\nFor SAS, this would be the location of the SASWORK folder.<br><br>\n`sessionId` can be used to poll session state using the\nGET /SASjsApi/session/{sessionId}/state endpoint."
+                    example: 20241028074744-54132-1730101664824
+            required:
+                - sessionId
+            type: object
+            additionalProperties: false
         LoginPayload:
             properties:
                 username:
@@ -805,6 +853,30 @@ paths:
                     application/json:
                         schema:
                             $ref: '#/components/schemas/ExecuteCodePayload'
+    /SASjsApi/code/trigger:
+        post:
+            operationId: TriggerCode
+            responses:
+                '200':
+                    description: Ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/TriggerCodeResponse'
+            description: 'Trigger Code on the Specified Runtime'
+            summary: 'Triggers code and returns SessionId immediately - does not wait for job completion'
+            tags:
+                - Code
+            security:
+                -
+                    bearerAuth: []
+            parameters: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/TriggerCodePayload'
     /SASjsApi/drive/deploy:
         post:
             operationId: Deploy
@@ -1777,6 +1849,30 @@ paths:
                 -
                     bearerAuth: []
             parameters: []
+    '/SASjsApi/session/{sessionId}/state':
+        get:
+            operationId: SessionState
+            responses:
+                '200':
+                    description: Ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/SessionState'
+            description: "The polling endpoint is currently implemented for single-server deployments only.<br>\nLoad balanced / grid topologies will be supported in a future release.<br>\nIf your site requires this, please reach out to SASjs Support."
+            summary: 'Get session state (initialising, pending, running, completed, failed).'
+            tags:
+                - Session
+            security:
+                -
+                    bearerAuth: []
+            parameters:
+                -
+                    in: path
+                    name: sessionId
+                    required: true
+                    schema:
+                        type: string
     /SASjsApi/stp/execute:
         get:
             operationId: ExecuteGetRequest
@@ -1798,7 +1894,7 @@ paths:
                     bearerAuth: []
             parameters:
                 -
-                    description: 'Location of code in SASjs Drive'
+                    description: 'Location of Stored Program in SASjs Drive.'
                     in: query
                     name: _program
                     required: true
@@ -1806,7 +1902,7 @@ paths:
                         type: string
                     example: /Projects/myApp/some/program
                 -
-                    description: 'Optional query param for setting debug mode, which will return the session log.'
+                    description: 'Optional query param for setting debug mode (returns the session log in the response body).'
                     in: query
                     name: _debug
                     required: false
@@ -1847,6 +1943,50 @@ paths:
                     application/json:
                         schema:
                             $ref: '#/components/schemas/ExecutePostRequestPayload'
+    /SASjsApi/stp/trigger:
+        post:
+            operationId: TriggerProgram
+            responses:
+                '200':
+                    description: Ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/TriggerProgramResponse'
+            description: 'Trigger Program on the Specified Runtime.'
+            summary: 'Triggers program and returns SessionId immediately - does not wait for program completion.'
+            tags:
+                - STP
+            security:
+                -
+                    bearerAuth: []
+            parameters:
+                -
+                    description: 'Location of code in SASjs Drive.'
+                    in: query
+                    name: _program
+                    required: true
+                    schema:
+                        type: string
+                    example: /Projects/myApp/some/program
+                -
+                    description: 'Optional query param for setting debug mode.'
+                    in: query
+                    name: _debug
+                    required: false
+                    schema:
+                        format: double
+                        type: number
+                    example: 131
+                -
+                    description: 'Optional query param for setting amount of minutes after the completion of the program when the session must be destroyed.'
+                    in: query
+                    name: expiresAfterMins
+                    required: false
+                    schema:
+                        format: double
+                        type: number
+                    example: 15
     /:
         get:
             operationId: Home

api/src/controllers/code.ts

@@ -1,27 +1,57 @@
 import express from 'express'
 import { Request, Security, Route, Tags, Post, Body } from 'tsoa'
-import { ExecutionController } from './internal'
+import { ExecutionController, getSessionController } from './internal'
 import {
   getPreProgramVariables,
   getUserAutoExec,
   ModeType,
-  parseLogToArray,
   RunTimeType
 } from '../utils'
 
 interface ExecuteCodePayload {
   /**
-   * Code of program
-   * @example "* Code HERE;"
+   * The code to be executed
+   * @example "* Your Code HERE;"
    */
   code: string
   /**
-   * runtime for program
+   * The runtime for the code - eg SAS, JS, PY or R
    * @example "js"
    */
   runTime: RunTimeType
 }
 
+interface TriggerCodePayload {
+  /**
+   * The code to be executed
+   * @example "* Your Code HERE;"
+   */
+  code: string
+  /**
+   * The runtime for the code - eg SAS, JS, PY or R
+   * @example "sas"
+   */
+  runTime: RunTimeType
+  /**
+   * Amount of minutes after the completion of the job when the session must be
+   * destroyed.
+   * @example 15
+   */
+  expiresAfterMins?: number
+}
+
+interface TriggerCodeResponse {
+  /**
+   * `sessionId` is the ID of the session and the name of the temporary folder
+   * used to store code outputs.<br><br>
+   * For SAS, this would be the location of the SASWORK folder.<br><br>
+   * `sessionId` can be used to poll session state using the
+   * GET /SASjsApi/session/{sessionId}/state endpoint.
+   * @example "20241028074744-54132-1730101664824"
+   */
+  sessionId: string
+}
+
 @Security('bearerAuth')
 @Route('SASjsApi/code')
 @Tags('Code')
@@ -44,6 +74,18 @@ export class CodeController {
   ): Promise<string | Buffer> {
     return executeCode(request, body)
   }
+
+  /**
+   * Trigger Code on the Specified Runtime
+   * @summary Triggers code and returns SessionId immediately - does not wait for job completion
+   */
+  @Post('/trigger')
+  public async triggerCode(
+    @Request() request: express.Request,
+    @Body() body: TriggerCodePayload
+  ): Promise<TriggerCodeResponse> {
+    return triggerCode(request, body)
+  }
 }
 
 const executeCode = async (
@@ -76,3 +118,49 @@ const executeCode = async (
     }
   }
 }
+
+const triggerCode = async (
+  req: express.Request,
+  { code, runTime, expiresAfterMins }: TriggerCodePayload
+): Promise<TriggerCodeResponse> => {
+  const { user } = req
+  const userAutoExec =
+    process.env.MODE === ModeType.Server
+      ? user?.autoExec
+      : await getUserAutoExec()
+
+  // get session controller based on runTime
+  const sessionController = getSessionController(runTime)
+
+  // get session
+  const session = await sessionController.getSession()
+
+  // add expiresAfterMins to session if provided
+  if (expiresAfterMins) {
+    // expiresAfterMins.used is set initially to false
+    session.expiresAfterMins = { mins: expiresAfterMins, used: false }
+  }
+
+  try {
+    // call executeProgram method of ExecutionController without awaiting
+    new ExecutionController().executeProgram({
+      program: code,
+      preProgramVariables: getPreProgramVariables(req),
+      vars: { ...req.query, _debug: 131 },
+      otherArgs: { userAutoExec },
+      runTime: runTime,
+      includePrintOutput: true,
+      session // session is provided
+    })
+
+    // return session id
+    return { sessionId: session.id }
+  } catch (err: any) {
+    throw {
+      code: 400,
+      status: 'failure',
+      message: 'Job execution failed.',
+      error: typeof err === 'object' ? err.toString() : err
+    }
+  }
+}

api/src/controllers/internal/Execution.ts

@@ -2,7 +2,7 @@ import path from 'path'
 import fs from 'fs'
 import { getSessionController, processProgram } from './'
 import { readFile, fileExists, createFile, readFileBinary } from '@sasjs/utils'
-import { PreProgramVars, Session, TreeNode } from '../../types'
+import { PreProgramVars, Session, TreeNode, SessionState } from '../../types'
 import {
   extractHeaders,
   getFilesFolder,
@@ -75,8 +75,7 @@ export class ExecutionController {
 
     const session =
       sessionByFileUpload ?? (await sessionController.getSession())
-    session.inUse = true
-    session.consumed = true
+    session.state = SessionState.running
 
     const logPath = path.join(session.path, 'log.log')
     const headersPath = path.join(session.path, 'stpsrv_header.txt')
@@ -121,7 +120,7 @@ export class ExecutionController {
       : ''
 
     // it should be deleted by scheduleSessionDestroy
-    session.inUse = false
+    session.state = SessionState.completed
 
     const resultParts = []
 
@@ -145,7 +144,9 @@ export class ExecutionController {
     return {
       httpHeaders,
       result:
-        isDebugOn(vars) || session.crashed ? resultParts.join(`\n`) : webout
+        isDebugOn(vars) || session.failureReason
+          ? resultParts.join(`\n`)
+          : webout
     }
   }
 

api/src/controllers/internal/FileUploadController.ts

@@ -2,11 +2,8 @@ import { Request, RequestHandler } from 'express'
 import multer from 'multer'
 import { uuidv4 } from '@sasjs/utils'
 import { getSessionController } from '.'
-import {
-  executeProgramRawValidation,
-  getRunTimeAndFilePath,
-  RunTimeType
-} from '../../utils'
+import { executeProgramRawValidation, getRunTimeAndFilePath } from '../../utils'
+import { SessionState } from '../../types'
 
 export class FileUploadController {
   private storage = multer.diskStorage({
@@ -56,9 +53,8 @@ export class FileUploadController {
     }
 
     const session = await sessionController.getSession()
-    // marking consumed true, so that it's not available
-    // as readySession for any other request
-    session.consumed = true
+    // change session state to 'running', so that it's not available for any other request
+    session.state = SessionState.running
 
     req.sasjsSession = session
 

api/src/controllers/internal/Session.ts

@@ -1,5 +1,5 @@
 import path from 'path'
-import { Session } from '../../types'
+import { Session, SessionState } from '../../types'
 import { promisify } from 'util'
 import { execFile } from 'child_process'
 import {
@@ -14,8 +14,7 @@ import {
   createFile,
   fileExists,
   generateTimestamp,
-  readFile,
-  isWindows
+  readFile
 } from '@sasjs/utils'
 
 const execFilePromise = promisify(execFile)
@@ -24,7 +23,9 @@ export class SessionController {
   protected sessions: Session[] = []
 
   protected getReadySessions = (): Session[] =>
-    this.sessions.filter((sess: Session) => sess.ready && !sess.consumed)
+    this.sessions.filter(
+      (session: Session) => session.state === SessionState.pending
+    )
 
   protected async createSession(): Promise<Session> {
     const sessionId = generateUniqueFileName(generateTimestamp())
@@ -40,19 +41,18 @@ export class SessionController {
 
     const session: Session = {
       id: sessionId,
-      ready: true,
-      inUse: true,
-      consumed: false,
-      completed: false,
+      state: SessionState.pending,
       creationTimeStamp,
       deathTimeStamp,
       path: sessionFolder
     }
 
     const headersPath = path.join(session.path, 'stpsrv_header.txt')
+
     await createFile(headersPath, 'content-type: text/html; charset=utf-8')
 
     this.sessions.push(session)
+
     return session
   }
 
@@ -67,6 +67,10 @@ export class SessionController {
 
     return session
   }
+
+  public getSessionById(id: string) {
+    return this.sessions.find((session) => session.id === id)
+  }
 }
 
 export class SASSessionController extends SessionController {
@@ -84,10 +88,7 @@ export class SASSessionController extends SessionController {
 
     const session: Session = {
       id: sessionId,
-      ready: false,
-      inUse: false,
-      consumed: false,
-      completed: false,
+      state: SessionState.initialising,
       creationTimeStamp,
       deathTimeStamp,
       path: sessionFolder
@@ -145,13 +146,20 @@ ${autoExecContent}`
       process.sasLoc!.endsWith('sas.exe') ? session.path : ''
     ])
       .then(() => {
-        session.completed = true
+        session.state = SessionState.completed
+
         process.logger.info('session completed', session)
       })
       .catch((err) => {
-        session.completed = true
-        session.crashed = err.toString()
-        process.logger.error('session crashed', session.id, session.crashed)
+        session.state = SessionState.failed
+
+        session.failureReason = err.toString()
+
+        process.logger.error(
+          'session crashed',
+          session.id,
+          session.failureReason
+        )
       })
 
     // we have a triggered session - add to array
@@ -168,15 +176,19 @@ ${autoExecContent}`
     const codeFilePath = path.join(session.path, 'code.sas')
 
     // TODO: don't wait forever
-    while ((await fileExists(codeFilePath)) && !session.crashed) {}
+    while (
+      (await fileExists(codeFilePath)) &&
+      session.state !== SessionState.failed
+    ) {}
 
-    if (session.crashed)
+    if (session.state === SessionState.failed) {
       process.logger.error(
         'session crashed! while waiting to be ready',
-        session.crashed
+        session.failureReason
       )
-
-    session.ready = true
+    } else {
+      session.state = SessionState.pending
+    }
   }
 
   private async deleteSession(session: Session) {
@@ -192,14 +204,31 @@ ${autoExecContent}`
   private scheduleSessionDestroy(session: Session) {
     setTimeout(
       async () => {
-        if (session.inUse) {
+        if (session.state === SessionState.running) {
           // adding 10 more minutes
-          const newDeathTimeStamp = parseInt(session.deathTimeStamp) + 10 * 1000
+          const newDeathTimeStamp =
+            parseInt(session.deathTimeStamp) + 10 * 60 * 1000
           session.deathTimeStamp = newDeathTimeStamp.toString()
 
           this.scheduleSessionDestroy(session)
         } else {
-          await this.deleteSession(session)
+          const { expiresAfterMins } = session
+
+          // delay session destroy if expiresAfterMins present
+          if (expiresAfterMins && session.state !== SessionState.completed) {
+            // calculate session death time using expiresAfterMins
+            const newDeathTimeStamp =
+              parseInt(session.deathTimeStamp) +
+              expiresAfterMins.mins * 60 * 1000
+            session.deathTimeStamp = newDeathTimeStamp.toString()
+
+            // set expiresAfterMins to true to avoid using it again
+            session.expiresAfterMins!.used = true
+
+            this.scheduleSessionDestroy(session)
+          } else {
+            await this.deleteSession(session)
+          }
         }
       },
       parseInt(session.deathTimeStamp) - new Date().getTime() - 100
@@ -231,9 +260,16 @@ data _null_;
   rc=filename(fname,getoption('SYSIN') );
   if rc = 0 and fexist(fname) then rc=fdelete(fname);
   rc=filename(fname);
-  /* now wait for the real SYSIN */
-  slept=0;
-  do until ( fileexist(getoption('SYSIN')) or slept>(60*15) );
+  /* now wait for the real SYSIN (location of code.sas) */
+  slept=0;fname='';
+  do until (slept>(60*15));
+    rc=filename(fname,getoption('SYSIN'));
+    if rc = 0 and fexist(fname) then do;
+      putlog fname=;
+      rc=filename(fname);
+      rc=sleep(0.01,1); /* wait just a little more */
+      stop;
+    end;
     slept=slept+sleep(0.01,1);
   end;
   stop;

api/src/controllers/internal/createJSProgram.ts

@@ -15,7 +15,7 @@ export const createJSProgram = async (
 ) => {
   const varStatments = Object.keys(vars).reduce(
     (computed: string, key: string) =>
-      `${computed}const ${key} = '${vars[key]}';\n`,
+      `${computed}const ${key} = \`${vars[key]}\`;\n`,
     ''
   )
 

api/src/controllers/internal/processProgram.ts

@@ -3,7 +3,7 @@ import { WriteStream, createWriteStream } from 'fs'
 import { execFile } from 'child_process'
 import { once } from 'stream'
 import { createFile, moveFile } from '@sasjs/utils'
-import { PreProgramVars, Session } from '../../types'
+import { PreProgramVars, Session, SessionState } from '../../types'
 import { RunTimeType } from '../../utils'
 import {
   ExecutionVars,
@@ -49,7 +49,7 @@ export const processProgram = async (
     await moveFile(codePath + '.bkp', codePath)
 
     // we now need to poll the session status
-    while (!session.completed) {
+    while (session.state !== SessionState.completed) {
       await delay(50)
     }
   } else {
@@ -114,13 +114,20 @@ export const processProgram = async (
 
     await execFilePromise(executablePath, [codePath], writeStream)
       .then(() => {
-        session.completed = true
+        session.state = SessionState.completed
+
         process.logger.info('session completed', session)
       })
       .catch((err) => {
-        session.completed = true
-        session.crashed = err.toString()
-        process.logger.error('session crashed', session.id, session.crashed)
+        session.state = SessionState.failed
+
+        session.failureReason = err.toString()
+
+        process.logger.error(
+          'session crashed',
+          session.id,
+          session.failureReason
+        )
       })
 
     // copy the code file to log and end write stream

api/src/controllers/session.ts

@@ -1,6 +1,8 @@
 import express from 'express'
 import { Request, Security, Route, Tags, Example, Get } from 'tsoa'
 import { UserResponse } from './user'
+import { getSessionController } from './internal'
+import { SessionState } from '../types'
 
 interface SessionResponse extends UserResponse {
   needsToUpdatePassword: boolean
@@ -26,6 +28,18 @@ export class SessionController {
   ): Promise<SessionResponse> {
     return session(request)
   }
+
+  /**
+   * The polling endpoint is currently implemented for single-server deployments only.<br>
+   * Load balanced / grid topologies will be supported in a future release.<br>
+   * If your site requires this, please reach out to SASjs Support.
+   * @summary Get session state (initialising, pending, running, completed, failed).
+   * @example completed
+   */
+  @Get('/:sessionId/state')
+  public async sessionState(sessionId: string): Promise<SessionState> {
+    return sessionState(sessionId)
+  }
 }
 
 const session = (req: express.Request) => ({
@@ -35,3 +49,23 @@ const session = (req: express.Request) => ({
   isAdmin: req.user!.isAdmin,
   needsToUpdatePassword: req.user!.needsToUpdatePassword
 })
+
+const sessionState = (sessionId: string): SessionState => {
+  for (let runTime of process.runTimes) {
+    // get session controller for each available runTime
+    const sessionController = getSessionController(runTime)
+
+    // get session by sessionId
+    const session = sessionController.getSessionById(sessionId)
+
+    // return session state if session was found
+    if (session) {
+      return session.state
+    }
+  }
+
+  throw {
+    code: 404,
+    message: `Session with ID '${sessionId}' was not found.`
+  }
+}

api/src/controllers/stp.ts

@@ -1,13 +1,16 @@
 import express from 'express'
 import { Request, Security, Route, Tags, Post, Body, Get, Query } from 'tsoa'
-import { ExecutionController, ExecutionVars } from './internal'
+import {
+  ExecutionController,
+  ExecutionVars,
+  getSessionController
+} from './internal'
 import {
   getPreProgramVariables,
   makeFilesNamesMap,
   getRunTimeAndFilePath
 } from '../utils'
 import { MulterFile } from '../types/Upload'
-import { debug } from 'console'
 
 interface ExecutePostRequestPayload {
   /**
@@ -17,6 +20,36 @@ interface ExecutePostRequestPayload {
   _program?: string
 }
 
+interface TriggerProgramPayload {
+  /**
+   * Location of SAS program.
+   * @example "/Public/somefolder/some.file"
+   */
+  _program: string
+  /**
+   * Amount of minutes after the completion of the program when the session must be
+   * destroyed.
+   * @example 15
+   */
+  expiresAfterMins?: number
+  /**
+   * Query param for setting debug mode.
+   */
+  _debug?: number
+}
+
+interface TriggerProgramResponse {
+  /**
+   * `sessionId` is the ID of the session and the name of the temporary folder
+   * used to store program outputs.<br><br>
+   * For SAS, this would be the location of the SASWORK folder.<br><br>
+   * `sessionId` can be used to poll session state using the
+   * GET /SASjsApi/session/{sessionId}/state endpoint.
+   * @example "20241028074744-54132-1730101664824"
+   */
+  sessionId: string
+}
+
 @Security('bearerAuth')
 @Route('SASjsApi/stp')
 @Tags('STP')
@@ -30,8 +63,8 @@ export class STPController {
    * https://server.sasjs.io/storedprograms
    *
    * @summary Execute a Stored Program, returns _webout and (optionally) log.
-   * @param _program Location of code in SASjs Drive
-   * @param _debug Optional query param for setting debug mode, which will return the session log.
+   * @param _program Location of Stored Program in SASjs Drive.
+   * @param _debug Optional query param for setting debug mode (returns the session log in the response body).
    * @example _program "/Projects/myApp/some/program"
    * @example _debug 131
    */
@@ -79,6 +112,26 @@ export class STPController {
 
     return execute(request, program!, vars, otherArgs)
   }
+
+  /**
+   * Trigger Program on the Specified Runtime.
+   * @summary Triggers program and returns SessionId immediately - does not wait for program completion.
+   * @param _program Location of code in SASjs Drive.
+   * @param expiresAfterMins Optional query param for setting amount of minutes after the completion of the program when the session must be destroyed.
+   * @param _debug Optional query param for setting debug mode.
+   * @example _program "/Projects/myApp/some/program"
+   * @example _debug 131
+   * @example expiresAfterMins 15
+   */
+  @Post('/trigger')
+  public async triggerProgram(
+    @Request() request: express.Request,
+    @Query() _program: string,
+    @Query() _debug?: number,
+    @Query() expiresAfterMins?: number
+  ): Promise<TriggerProgramResponse> {
+    return triggerProgram(request, { _program, _debug, expiresAfterMins })
+  }
 }
 
 const execute = async (
@@ -117,3 +170,52 @@ const execute = async (
     }
   }
 }
+
+const triggerProgram = async (
+  req: express.Request,
+  { _program, _debug, expiresAfterMins }: TriggerProgramPayload
+): Promise<TriggerProgramResponse> => {
+  try {
+    // put _program query param into vars object
+    const vars: { [key: string]: string | number } = { _program }
+
+    // if present add _debug query param to vars object
+    if (_debug) {
+      vars._debug = _debug
+    }
+
+    // get code path and runTime
+    const { codePath, runTime } = await getRunTimeAndFilePath(_program)
+
+    // get session controller based on runTime
+    const sessionController = getSessionController(runTime)
+
+    // get session
+    const session = await sessionController.getSession()
+
+    // add expiresAfterMins to session if provided
+    if (expiresAfterMins) {
+      // expiresAfterMins.used is set initially to false
+      session.expiresAfterMins = { mins: expiresAfterMins, used: false }
+    }
+
+    // call executeFile method of ExecutionController without awaiting
+    new ExecutionController().executeFile({
+      programPath: codePath,
+      runTime,
+      preProgramVariables: getPreProgramVariables(req),
+      vars,
+      session
+    })
+
+    // return session id
+    return { sessionId: session.id }
+  } catch (err: any) {
+    throw {
+      code: 400,
+      status: 'failure',
+      message: 'Job execution failed.',
+      error: typeof err === 'object' ? err.toString() : err
+    }
+  }
+}

api/src/controllers/user.ts

@@ -285,7 +285,7 @@ const getUser = async (
     username: user.username,
     isActive: user.isActive,
     isAdmin: user.isAdmin,
-    autoExec: getAutoExec ? user.autoExec ?? '' : undefined,
+    autoExec: getAutoExec ? (user.autoExec ?? '') : undefined,
     groups: user.groups
   }
 }

api/src/model/Group.ts

@@ -76,7 +76,7 @@ groupSchema.post('save', function (group: IGroup, next: Function) {
 })
 
 // pre remove hook to remove all references of group from users
-groupSchema.pre('remove', async function () {
+groupSchema.pre('remove', async function (this: IGroupDocument) {
   const userIds = this.users
   await Promise.all(
     userIds.map(async (userId) => {

api/src/routes/api/code.ts

@@ -1,5 +1,5 @@
 import express from 'express'
-import { runCodeValidation } from '../../utils'
+import { runCodeValidation, triggerCodeValidation } from '../../utils'
 import { CodeController } from '../../controllers/'
 
 const runRouter = express.Router()
@@ -28,4 +28,22 @@ runRouter.post('/execute', async (req, res) => {
   }
 })
 
+runRouter.post('/trigger', async (req, res) => {
+  const { error, value: body } = triggerCodeValidation(req.body)
+  if (error) return res.status(400).send(error.details[0].message)
+
+  try {
+    const response = await controller.triggerCode(req, body)
+
+    res.status(200)
+    res.send(response)
+  } catch (err: any) {
+    const statusCode = err.code
+
+    delete err.code
+
+    res.status(statusCode).send(err)
+  }
+})
+
 export default runRouter

api/src/routes/api/session.ts

@@ -1,16 +1,37 @@
 import express from 'express'
 import { SessionController } from '../../controllers'
+import { sessionIdValidation } from '../../utils'
 
 const sessionRouter = express.Router()
 
+const controller = new SessionController()
+
 sessionRouter.get('/', async (req, res) => {
-  const controller = new SessionController()
   try {
     const response = await controller.session(req)
+
     res.send(response)
   } catch (err: any) {
     res.status(403).send(err.toString())
   }
 })
 
+sessionRouter.get('/:sessionId/state', async (req, res) => {
+  const { error, value: params } = sessionIdValidation(req.params)
+  if (error) return res.status(400).send(error.details[0].message)
+
+  try {
+    const response = await controller.sessionState(params.sessionId)
+
+    res.status(200)
+    res.send(response)
+  } catch (err: any) {
+    const statusCode = err.code
+
+    delete err.code
+
+    res.status(statusCode).send(err)
+  }
+})
+
 export default sessionRouter

api/src/routes/api/spec/stp.spec.ts

@@ -25,7 +25,7 @@ import {
   SASSessionController
 } from '../../../controllers/internal'
 import * as ProcessProgramModule from '../../../controllers/internal/processProgram'
-import { Session } from '../../../types'
+import { Session, SessionState } from '../../../types'
 
 const clientId = 'someclientID'
 
@@ -493,10 +493,7 @@ const mockedGetSession = async () => {
 
   const session: Session = {
     id: sessionId,
-    ready: true,
-    inUse: true,
-    consumed: false,
-    completed: false,
+    state: SessionState.pending,
     creationTimeStamp,
     deathTimeStamp,
     path: sessionFolder

api/src/routes/api/stp.ts

@@ -1,5 +1,8 @@
 import express from 'express'
-import { executeProgramRawValidation } from '../../utils'
+import {
+  executeProgramRawValidation,
+  triggerProgramValidation
+} from '../../utils'
 import { STPController } from '../../controllers/'
 import { FileUploadController } from '../../controllers/internal'
 
@@ -69,4 +72,28 @@ stpRouter.post(
   }
 )
 
+stpRouter.post('/trigger', async (req, res) => {
+  const { error, value: query } = triggerProgramValidation(req.query)
+
+  if (error) return res.status(400).send(error.details[0].message)
+
+  try {
+    const response = await controller.triggerProgram(
+      req,
+      query._program,
+      query._debug,
+      query.expiresAfterMins
+    )
+
+    res.status(200)
+    res.send(response)
+  } catch (err: any) {
+    const statusCode = err.code
+
+    delete err.code
+
+    res.status(statusCode).send(err)
+  }
+})
+
 export default stpRouter

api/src/types/Session.ts

@@ -1,11 +1,16 @@
+export enum SessionState {
+  initialising = 'initialising', // session is initialising and not ready to be used yet
+  pending = 'pending', // session is ready to be used
+  running = 'running', // session is in use
+  completed = 'completed', // session is completed and can be destroyed
+  failed = 'failed' // session failed
+}
 export interface Session {
   id: string
-  ready: boolean
+  state: SessionState
   creationTimeStamp: string
   deathTimeStamp: string
   path: string
-  inUse: boolean
-  consumed: boolean
-  completed: boolean
-  crashed?: string
+  expiresAfterMins?: { mins: number; used: boolean }
+  failureReason?: string
 }

api/src/utils/setProcessVariables.ts

@@ -1,9 +1,31 @@
 import path from 'path'
-import { createFolder, getAbsolutePath, getRealPath } from '@sasjs/utils'
-
+import {
+  createFolder,
+  getAbsolutePath,
+  getRealPath,
+  fileExists
+} from '@sasjs/utils'
+import dotenv from 'dotenv'
 import { connectDB, getDesktopFields, ModeType, RunTimeType, SECRETS } from '.'
 
 export const setProcessVariables = async () => {
+  const { execPath } = process
+
+  // Check if execPath ends with 'api-macos' to determine executable for MacOS.
+  // This is needed to fix picking .env file issue in MacOS executable.
+  if (execPath) {
+    const envPathSplitted = execPath.split(path.sep)
+
+    if (envPathSplitted.pop() === 'api-macos') {
+      const envPath = path.join(envPathSplitted.join(path.sep), '.env')
+
+      // Override environment variables from envPath if file exists
+      if (await fileExists(envPath)) {
+        dotenv.config({ path: envPath, override: true })
+      }
+    }
+  }
+
   const { MODE, RUN_TIMES } = process.env
 
   if (MODE === ModeType.Server) {
@@ -21,6 +43,7 @@ export const setProcessVariables = async () => {
   if (process.env.NODE_ENV === 'test') {
     process.sasjsRoot = path.join(process.cwd(), 'sasjs_root')
     process.driveLoc = path.join(process.cwd(), 'sasjs_root', 'drive')
+
     return
   }
 
@@ -41,7 +64,9 @@ export const setProcessVariables = async () => {
 
   const { SASJS_ROOT } = process.env
   const absPath = getAbsolutePath(SASJS_ROOT ?? 'sasjs_root', process.cwd())
+
   await createFolder(absPath)
+
   process.sasjsRoot = getRealPath(absPath)
 
   const { DRIVE_LOCATION } = process.env
@@ -49,6 +74,7 @@ export const setProcessVariables = async () => {
     DRIVE_LOCATION ?? path.join(process.sasjsRoot, 'drive'),
     process.cwd()
   )
+
   await createFolder(absDrivePath)
   process.driveLoc = getRealPath(absDrivePath)
 
@@ -57,7 +83,9 @@ export const setProcessVariables = async () => {
     LOG_LOCATION ?? path.join(process.sasjsRoot, 'logs'),
     process.cwd()
   )
+
   await createFolder(absLogsPath)
+
   process.logsLoc = getRealPath(absLogsPath)
 
   process.logsUUID = 'SASJS_LOGS_SEPARATOR_163ee17b6ff24f028928972d80a26784'

api/src/utils/validation.ts

@@ -178,6 +178,13 @@ export const runCodeValidation = (data: any): Joi.ValidationResult =>
     runTime: Joi.string().valid(...process.runTimes)
   }).validate(data)
 
+export const triggerCodeValidation = (data: any): Joi.ValidationResult =>
+  Joi.object({
+    code: Joi.string().required(),
+    runTime: Joi.string().valid(...process.runTimes),
+    expiresAfterMins: Joi.number().greater(0)
+  }).validate(data)
+
 export const executeProgramRawValidation = (data: any): Joi.ValidationResult =>
   Joi.object({
     _program: Joi.string().required(),
@@ -185,3 +192,17 @@ export const executeProgramRawValidation = (data: any): Joi.ValidationResult =>
   })
     .pattern(/^/, Joi.alternatives(Joi.string(), Joi.number()))
     .validate(data)
+
+export const triggerProgramValidation = (data: any): Joi.ValidationResult =>
+  Joi.object({
+    _program: Joi.string().required(),
+    _debug: Joi.number(),
+    expiresAfterMins: Joi.number().greater(0)
+  })
+    .pattern(/^/, Joi.alternatives(Joi.string(), Joi.number()))
+    .validate(data)
+
+export const sessionIdValidation = (data: any): Joi.ValidationResult =>
+  Joi.object({
+    sessionId: Joi.string().required()
+  }).validate(data)

web/package.json

@@ -4,9 +4,7 @@
   "private": true,
   "scripts": {
     "start": "webpack-dev-server --config webpack.dev.ts --hot",
-    "build": "webpack --config webpack.prod.ts",
-    "lint": "npx prettier --check \"src/**/*.{ts,tsx,js,jsx,html,css,sass,less,yml,md,graphql}\"",
-    "lint:fix": "npx prettier --write \"src/**/*.{ts,tsx,js,jsx,html,css,sass,less,yml,md,graphql}\""
+    "build": "webpack --config webpack.prod.ts"
   },
   "dependencies": {
     "@emotion/react": "^11.4.1",
@@ -21,7 +19,7 @@
     "@types/jest": "^26.0.24",
     "@types/node": "^12.20.28",
     "@types/react": "^17.0.27",
-    "axios": "^0.24.0",
+    "axios": "^1.12.2",
     "monaco-editor": "^0.33.0",
     "monaco-editor-webpack-plugin": "^7.0.1",
     "react": "^17.0.2",
@@ -57,14 +55,14 @@
     "file-loader": "^6.2.0",
     "html-webpack-plugin": "5.5.0",
     "path": "0.12.7",
-    "prettier": "^3.0.3",
+    "prettier": "^2.4.1",
     "sass": "^1.44.0",
     "sass-loader": "^12.3.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.2.6",
     "typescript": "^4.5.2",
     "typescript-plugin-css-modules": "^5.0.1",
-    "webpack": "5.64.3",
+    "webpack": "^5.101.3",
     "webpack-cli": "^4.9.2",
     "webpack-dev-server": "4.7.4"
   },

web/src/index.css

@@ -1,15 +1,15 @@
 body {
   margin: 0;
-  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
-    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
-    sans-serif;
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu',
+    'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }
 
 code {
-  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
-    monospace;
+  font-family:
+    source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace;
 }
 
 .container {