chore: docs finalized for stp and others

api/src/controllers/auth.ts

@@ -19,7 +19,7 @@ export default class AuthController {
     delete AuthController.authCodes[userId][clientId]
 
   /**
-   * Accept a valid username/password, plus a CLIENT_ID, and return an AUTH_CODE
+   * @summary Accept a valid username/password, plus a CLIENT_ID, and return an AUTH_CODE
    *
    */
   @Example<AuthorizeResponse>({
@@ -33,7 +33,7 @@ export default class AuthController {
   }
 
   /**
-   * Accepts client/auth code and returns access/refresh tokens
+   * @summary Accepts client/auth code and returns access/refresh tokens
    *
    */
   @Example<TokenResponse>({
@@ -46,7 +46,7 @@ export default class AuthController {
   }
 
   /**
-   * Returns new access/refresh tokens
+   * @summary Returns new access/refresh tokens
    *
    */
   @Example<TokenResponse>({
@@ -62,7 +62,7 @@ export default class AuthController {
   }
 
   /**
-   * Logout terminate access/refresh tokens and returns nothing
+   * @summary Logout terminate access/refresh tokens and returns nothing
    *
    */
   @Security('bearerAuth')

api/src/controllers/client.ts

@@ -7,7 +7,7 @@ import Client, { ClientPayload } from '../model/Client'
 @Tags('Client')
 export default class ClientController {
   /**
-   * Create client with the following attributes: ClientId, ClientSecret. Admin only task.
+   * @summary Create client with the following attributes: ClientId, ClientSecret. Admin only task.
    *
    */
   @Example<ClientPayload>({

api/src/controllers/drive.ts

@@ -13,7 +13,7 @@ import {
 import { fileExists, readFile, createFile } from '@sasjs/utils'
 import { createFileTree, ExecutionController, getTreeExample } from '.'
 
-import { FileTree, isFileQuery, isFileTree, TreeNode } from '../types'
+import { FileTree, isFileTree, TreeNode } from '../types'
 import path from 'path'
 import { getTmpFilesFolderPath } from '../utils'
 
@@ -77,7 +77,7 @@ const execDeployErrorResponse: DeployResponse = {
 @Tags('Drive')
 export class DriveController {
   /**
-   * Creates/updates files within SASjs Drive using provided payload.
+   * @summary Creates/updates files within SASjs Drive using provided payload.
    *
    */
   @Example<DeployResponse>(successDeployResponse)
@@ -89,8 +89,9 @@ export class DriveController {
   }
 
   /**
-   * Get file from SASjs Drive
-   *
+   * @summary Get file from SASjs Drive
+   * @query filePath Location of SAS program
+   * @example filePath "/Public/somefolder/some.file"
    */
   @Example<GetFileResponse>({
     status: 'success',
@@ -106,7 +107,7 @@ export class DriveController {
   }
 
   /**
-   * Modify a file in SASjs Drive
+   * @summary Modify a file in SASjs Drive
    *
    */
   @Example<UpdateFileResponse>({
@@ -124,7 +125,7 @@ export class DriveController {
   }
 
   /**
-   * Fetch file tree within SASjs Drive.
+   * @summary Fetch file tree within SASjs Drive.
    *
    */
   @Get('/filetree')

api/src/controllers/group.ts

@@ -33,7 +33,7 @@ interface GroupDetailsResponse {
 @Tags('Group')
 export default class GroupController {
   /**
-   * Get list of all groups (groupName and groupDescription). All users can request this.
+   * @summary Get list of all groups (groupName and groupDescription). All users can request this.
    *
    */
   @Example<GroupResponse[]>([
@@ -49,7 +49,7 @@ export default class GroupController {
   }
 
   /**
-   * Create a new group. Admin only.
+   * @summary Create a new group. Admin only.
    *
    */
   @Example<GroupDetailsResponse>({
@@ -67,7 +67,7 @@ export default class GroupController {
   }
 
   /**
-   * Get list of members of a group (userName). All users can request this.
+   * @summary Get list of members of a group (userName). All users can request this.
    * @param groupId The group's identifier
    * @example groupId 1234
    */
@@ -79,7 +79,7 @@ export default class GroupController {
   }
 
   /**
-   * Add a user to a group. Admin task only.
+   * @summary Add a user to a group. Admin task only.
    * @param groupId The group's identifier
    * @example groupId "1234"
    * @param userId The user's identifier
@@ -101,7 +101,7 @@ export default class GroupController {
   }
 
   /**
-   * Remove a user to a group. Admin task only.
+   * @summary Remove a user to a group. Admin task only.
    * @param groupId The group's identifier
    * @example groupId "1234"
    * @param userId The user's identifier
@@ -123,7 +123,7 @@ export default class GroupController {
   }
 
   /**
-   * Delete a group. Admin task only.
+   * @summary Delete a group. Admin task only.
    * @param groupId The group's identifier
    * @example groupId 1234
    */

api/src/controllers/stp.ts

@@ -0,0 +1,151 @@
+import express from 'express'
+import path from 'path'
+import {
+  Request,
+  Security,
+  Route,
+  Tags,
+  Example,
+  Post,
+  Body,
+  Get,
+  Query
+} from 'tsoa'
+import { ExecutionController } from '.'
+import { PreProgramVars } from '../types'
+import { getTmpFilesFolderPath, makeFilesNamesMap } from '../utils'
+
+interface ExecuteReturnJsonPayload {
+  /**
+   * Location of SAS program
+   * @example "/Public/somefolder/some.file"
+   */
+  _program?: string
+}
+interface ExecuteReturnJsonResponse {
+  status: string
+  log?: string
+  result?: string
+  message?: string
+}
+
+@Security('bearerAuth')
+@Route('SASjsApi/client')
+@Tags('STP')
+export default class STPController {
+  /**
+   * Trigger a SAS program using it's location in the _program parameter.
+   * Enable debugging using the _debug parameter.
+   * Additional URL parameters are turned into SAS macro variables.
+   * Any files provided are placed into the session and
+   * corresponding _WEBIN_XXX variables are created.
+   * @summary Execute Stored Program, return raw content
+   * @query _program Location of SAS program
+   * @example _program "/Public/somefolder/some.file"
+   */
+  @Get('/execute')
+  public async executeReturnRaw(
+    @Request() request: express.Request,
+    @Query() _program: string
+  ): Promise<string> {
+    return executeReturnRaw(request, _program)
+  }
+  /**
+   * Trigger a SAS program using it's location in the _program parameter.
+   * Enable debugging using the _debug parameter.
+   * Additional URL parameters are turned into SAS macro variables.
+   * Any files provided are placed into the session and
+   * corresponding _WEBIN_XXX variables are created.
+   * @summary Execute Stored Program, return JSON
+   * @query _program Location of SAS program
+   * @example _program "/Public/somefolder/some.file"
+   */
+  @Post('/execute')
+  public async executeReturnJson(
+    @Request() request: express.Request,
+    @Body() body: ExecuteReturnJsonPayload,
+    @Query() _program?: string
+  ): Promise<ExecuteReturnJsonResponse> {
+    const program = _program ?? body._program
+    return executeReturnJson(request, program!)
+  }
+}
+
+const executeReturnRaw = async (
+  req: express.Request,
+  _program: string
+): Promise<string> => {
+  const sasCodePath =
+    path
+      .join(getTmpFilesFolderPath(), _program)
+      .replace(new RegExp('/', 'g'), path.sep) + '.sas'
+
+  try {
+    const result = await new ExecutionController().execute(
+      sasCodePath,
+      getPreProgramVariables(req),
+      undefined,
+      undefined,
+      {
+        ...req.query
+      }
+    )
+
+    return result as string
+  } catch (err) {
+    throw {
+      code: 400,
+      status: 'failure',
+      message: 'Job execution failed.',
+      ...(typeof err === 'object' ? err : { details: err })
+    }
+  }
+}
+
+const executeReturnJson = async (
+  req: any,
+  _program: string
+): Promise<ExecuteReturnJsonResponse> => {
+  const sasCodePath =
+    path
+      .join(getTmpFilesFolderPath(), _program)
+      .replace(new RegExp('/', 'g'), path.sep) + '.sas'
+
+  const filesNamesMap = req.files?.length ? makeFilesNamesMap(req.files) : null
+
+  try {
+    const jsonResult: any = await new ExecutionController().execute(
+      sasCodePath,
+      getPreProgramVariables(req),
+      undefined,
+      req.sasSession,
+      { ...req.query, ...req.body },
+      { filesNamesMap: filesNamesMap },
+      true
+    )
+    return {
+      status: 'success',
+      result: jsonResult.result,
+      log: jsonResult.log
+    }
+  } catch (err) {
+    throw {
+      status: 'failure',
+      message: 'Job execution failed.',
+      ...(typeof err === 'object' ? err : { details: err })
+    }
+  }
+}
+
+const getPreProgramVariables = (req: any): PreProgramVars => {
+  const host = req.get('host')
+  const protocol = req.protocol + '://'
+  const { user, accessToken } = req
+  return {
+    username: user.username,
+    userId: user.userId,
+    displayName: user.displayName,
+    serverUrl: protocol + host,
+    accessToken
+  }
+}

api/src/controllers/user.ts

@@ -34,7 +34,7 @@ interface UserDetailsResponse {
 @Tags('User')
 export default class UserController {
   /**
-   * Get list of all users (username, displayname). All users can request this.
+   * @summary Get list of all users (username, displayname). All users can request this.
    *
    */
   @Example<UserResponse[]>([
@@ -55,7 +55,7 @@ export default class UserController {
   }
 
   /**
-   * Create user with the following attributes: UserId, UserName, Password, isAdmin, isActive. Admin only task.
+   * @summary Create user with the following attributes: UserId, UserName, Password, isAdmin, isActive. Admin only task.
    *
    */
   @Example<UserDetailsResponse>({
@@ -73,7 +73,7 @@ export default class UserController {
   }
 
   /**
-   * Get user properties - such as group memberships, userName, displayName.
+   * @summary Get user properties - such as group memberships, userName, displayName.
    * @param userId The user's identifier
    * @example userId 1234
    */
@@ -83,7 +83,7 @@ export default class UserController {
   }
 
   /**
-   * Update user properties - such as displayName. Can be performed either by admins, or the user in question.
+   * @summary Update user properties - such as displayName. Can be performed either by admins, or the user in question.
    * @param userId The user's identifier
    * @example userId "1234"
    */
@@ -103,7 +103,7 @@ export default class UserController {
   }
 
   /**
-   * Delete a user. Can be performed either by admins, or the user in question.
+   * @summary Delete a user. Can be performed either by admins, or the user in question.
    * @param userId The user's identifier
    * @example userId 1234
    */

api/src/routes/api/drive.ts

@@ -1,13 +1,6 @@
 import express from 'express'
-import path from 'path'
-import { ExecutionController } from '../../controllers'
 import { DriveController } from '../../controllers/drive'
-import { isFileQuery } from '../../types'
-import {
-  getFileDriveValidation,
-  getTmpFilesFolderPath,
-  updateFileDriveValidation
-} from '../../utils'
+import { getFileDriveValidation, updateFileDriveValidation } from '../../utils'
 
 const driveRouter = express.Router()
 

api/src/routes/api/stp.ts

@@ -1,39 +1,26 @@
 import express from 'express'
-import { isExecutionQuery, PreProgramVars } from '../../types'
-import path from 'path'
-import { getTmpFilesFolderPath, makeFilesNamesMap } from '../../utils'
-import { ExecutionController, FileUploadController } from '../../controllers'
+import { executeProgramRawValidation } from '../../utils'
+import STPController from '../../controllers/stp'
+import { FileUploadController } from '../../controllers'
 
 const stpRouter = express.Router()
 
 const fileUploadController = new FileUploadController()
+const controller = new STPController()
 
 stpRouter.get('/execute', async (req, res) => {
-  if (isExecutionQuery(req.query)) {
-    let sasCodePath =
-      path
-        .join(getTmpFilesFolderPath(), req.query._program)
-        .replace(new RegExp('/', 'g'), path.sep) + '.sas'
+  const { error, value: query } = executeProgramRawValidation(req.query)
+  if (error) return res.status(400).send(error.details[0].message)
 
-    await new ExecutionController()
-      .execute(sasCodePath, getPreProgramVariables(req), undefined, undefined, {
-        ...req.query
-      })
-      .then((result: {}) => {
-        res.status(200).send(result)
-      })
-      .catch((err: {} | string) => {
-        res.status(400).send({
-          status: 'failure',
-          message: 'Job execution failed.',
-          ...(typeof err === 'object' ? err : { details: err })
-        })
-      })
-  } else {
-    res.status(400).send({
-      status: 'failure',
-      message: `Please provide the location of SAS code`
-    })
+  try {
+    const response = await controller.executeReturnRaw(req, query._program)
+    res.send(response)
+  } catch (err: any) {
+    const statusCode = err.code
+
+    delete err.code
+
+    res.status(statusCode).send(err)
   }
 })
 
@@ -42,68 +29,27 @@ stpRouter.post(
   fileUploadController.preuploadMiddleware,
   fileUploadController.getMulterUploadObject().any(),
   async (req: any, res: any) => {
-    let _program
-    if (isExecutionQuery(req.query)) {
-      _program = req.query._program
-    } else if (isExecutionQuery(req.body)) {
-      _program = req.body._program
-    }
+    const { error: errQ, value: query } = executeProgramRawValidation(req.query)
+    if (errQ) return res.status(400).send(errQ.details[0].message)
 
-    if (_program) {
-      let sasCodePath =
-        path
-          .join(getTmpFilesFolderPath(), _program)
-          .replace(new RegExp('/', 'g'), path.sep) + '.sas'
+    const { error: errB, value: body } = executeProgramRawValidation(req.body)
+    if (errB) return res.status(400).send(errB.details[0].message)
 
-      let filesNamesMap = null
+    try {
+      const response = await controller.executeReturnJson(
+        req,
+        query,
+        body?._program
+      )
+      res.send(response)
+    } catch (err: any) {
+      const statusCode = err.code
 
-      if (req.files && req.files.length > 0) {
-        filesNamesMap = makeFilesNamesMap(req.files)
-      }
+      delete err.code
 
-      await new ExecutionController()
-        .execute(
-          sasCodePath,
-          getPreProgramVariables(req),
-          undefined,
-          req.sasSession,
-          { ...req.query, ...req.body },
-          { filesNamesMap: filesNamesMap },
-          true
-        )
-        .then((result: {}) => {
-          res.status(200).send({
-            status: 'success',
-            ...result
-          })
-        })
-        .catch((err: {} | string) => {
-          res.status(400).send({
-            status: 'failure',
-            message: 'Job execution failed.',
-            ...(typeof err === 'object' ? err : { details: err })
-          })
-        })
-    } else {
-      res.status(400).send({
-        status: 'failure',
-        message: `Please provide the location of SAS code`
-      })
+      res.status(statusCode).send(err)
     }
   }
 )
 
-const getPreProgramVariables = (req: any): PreProgramVars => {
-  const host = req.get('host')
-  const protocol = req.protocol + '://'
-  const { user, accessToken } = req
-  return {
-    username: user.username,
-    userId: user.userId,
-    displayName: user.displayName,
-    serverUrl: protocol + host,
-    accessToken
-  }
-}
-
 export default stpRouter

api/src/routes/web/web.ts

@@ -1,8 +1,6 @@
 import express from 'express'
-import { isExecutionQuery } from '../../types'
 import path from 'path'
-import { getTmpFilesFolderPath, getWebBuildFolderPath } from '../../utils'
-import { ExecutionController } from '../../controllers'
+import { getWebBuildFolderPath } from '../../utils'
 
 const webRouter = express.Router()
 

api/src/utils/validation.ts

@@ -76,3 +76,10 @@ export const updateFileDriveValidation = (data: any): Joi.ValidationResult =>
     filePath: Joi.string().required(),
     fileContent: Joi.string().required()
   }).validate(data)
+
+export const executeProgramRawValidation = (data: any): Joi.ValidationResult =>
+  Joi.object({
+    _program: Joi.string().required
+  })
+    .pattern(/\w\d/, Joi.string())
+    .validate(data)