@rapidrest/service-core 1.0.0-beta.1

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/Query.md

@@ -0,0 +1,26 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / Query
+
+# Function: Query()
+
+> **Query**(`name?`): (`target`, `propertyKey`, `index`) => `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:265](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L265)
+
+Injects the value of the specified query parameter with the given name as the value of the decorated argument. If
+no name is specified the entire request query will be injected.
+
+## Parameters
+
+### name?
+
+`string` \| `undefined`
+
+THe name of the query parameter whose value will be injected.
+
+## Returns
+
+(`target`, `propertyKey`, `index`) => `void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/Request.md

@@ -0,0 +1,31 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / Request
+
+# Function: Request()
+
+> **Request**(`target`, `propertyKey`, `index`): `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:276](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L276)
+
+Injects the Express request object as the value of the decorated argument.
+
+## Parameters
+
+### target
+
+`any`
+
+### propertyKey
+
+`string`
+
+### index
+
+`number`
+
+## Returns
+
+`void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/RequiresRole.md

@@ -0,0 +1,26 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / RequiresRole
+
+# Function: RequiresRole()
+
+> **RequiresRole**(`roles`): (`target`, `propertyKey`, `descriptor`) => `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:297](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L297)
+
+Indicates that the client must be an authenticated user with at least one of the specified role(s) to process the
+request.
+
+## Parameters
+
+### roles
+
+`string` \| `string`[]
+
+The role(s) that an authenticated user must have to make the request.
+
+## Returns
+
+(`target`, `propertyKey`, `descriptor`) => `void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/Response.md

@@ -0,0 +1,31 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / Response
+
+# Function: Response()
+
+> **Response**(`target`, `propertyKey`, `index`): `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:285](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L285)
+
+Injects the Express response object as the value of the decorated argument.
+
+## Parameters
+
+### target
+
+`any`
+
+### propertyKey
+
+`string`
+
+### index
+
+`number`
+
+## Returns
+
+`void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/Route.md

@@ -0,0 +1,25 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / Route
+
+# Function: Route()
+
+> **Route**(`paths`): (`target`) => `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:310](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L310)
+
+Indicates that the decorated class contains Express route definitions.
+
+## Parameters
+
+### paths
+
+`string` \| `string`[]
+
+The base path(s) that all route definitions will use.
+
+## Returns
+
+(`target`) => `void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/Socket.md

@@ -0,0 +1,33 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / Socket
+
+# Function: Socket()
+
+> **Socket**(`target`, `propertyKey`, `index`): `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:323](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L323)
+
+Injects the underlying Socket object associated with the request as the value of the decorated argument.
+When the handler function is for a WebSocket request, the returned socket will be the newly established
+WebSocket connection.
+
+## Parameters
+
+### target
+
+`any`
+
+### propertyKey
+
+`string`
+
+### index
+
+`number`
+
+## Returns
+
+`void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/User.md

@@ -0,0 +1,31 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / User
+
+# Function: User()
+
+> **User**(`target`, `propertyKey`, `index`): `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:332](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L332)
+
+Injects the authenticated user object as the value of the decorated argument.
+
+## Parameters
+
+### target
+
+`any`
+
+### propertyKey
+
+`string`
+
+### index
+
+`number`
+
+## Returns
+
+`void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/Validate.md

@@ -0,0 +1,25 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / Validate
+
+# Function: Validate()
+
+> **Validate**(`func`): (`target`, `propertyKey`, `descriptor`) => `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:343](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L343)
+
+Indicates a validation function to execute in order to verify an incoming requests payload.
+
+## Parameters
+
+### func
+
+`string` \| `Function`
+
+The validation function to execute that will verify the request payload.
+
+## Returns
+
+(`target`, `propertyKey`, `descriptor`) => `void`

package/docs/reference/@rapidrest/namespaces/RouteDecorators/functions/WebSocket.md

@@ -0,0 +1,25 @@
+[**@rapidrest/service-core**](../../../../README.md)
+
+***
+
+[@rapidrest/service-core](../../../../globals.md) / [RouteDecorators](../README.md) / WebSocket
+
+# Function: WebSocket()
+
+> **WebSocket**(`path?`): (`target`, `propertyKey`, `descriptor`) => `void`
+
+Defined in: [src/decorators/RouteDecorators.ts:356](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/decorators/RouteDecorators.ts#L356)
+
+Indicates that the decorated function handles incoming `WebSocket` upgrade requests at the given sub-path.
+
+## Parameters
+
+### path?
+
+`string`
+
+The sub-path that the route will handle requests for.
+
+## Returns
+
+(`target`, `propertyKey`, `descriptor`) => `void`

package/docs/reference/README.md

@@ -0,0 +1,20 @@
+**@rapidrest/service-core**
+
+***
+
+# RapidREST: service-core
+
+[![pipeline status](https://gitlab.rapidrest.com/rapidrest/rapidrestjs/service-core/badges/master/pipeline.svg)](https://gitlab.rapidrest.com/rapidrest/rapidrestjs/service-core/-/commits/master)
+[![coverage report](https://gitlab.rapidrest.com/rapidrest/rapidrestjs/service-core/badges/master/coverage.svg)](https://gitlab.rapidrest.com/rapidrest/rapidrestjs/service-core/-/commits/master)
+
+Provides common functionality and utilities for RapidREST based REST API service projects.
+
+## NPM
+```
+npm i @rapidrest/service-core
+```
+
+## Yarn
+```
+yarn add @rapidrest/service-core
+```

package/docs/reference/classes/ACLUtils.md

@@ -0,0 +1,251 @@
+[**@rapidrest/service-core**](../README.md)
+
+***
+
+[@rapidrest/service-core](../globals.md) / ACLUtils
+
+# Class: ACLUtils
+
+Defined in: [src/security/ACLUtils.ts:22](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L22)
+
+Common utility functions for working with `AccessControlList` objects and validating user permissions.
+
+## Constructors
+
+### Constructor
+
+> **new ACLUtils**(): `ACLUtils`
+
+#### Returns
+
+`ACLUtils`
+
+## Methods
+
+### checkRequestPerms()
+
+> **checkRequestPerms**(`uid`, `user`, `req`): `Promise`\<`boolean`\>
+
+Defined in: [src/security/ACLUtils.ts:73](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L73)
+
+Validates that the user has permission to perform the request operation against the URL path for the
+provided request. If ACLUtils has not been initialized or the `acl` datastore has not been configured
+then always returns `true`.
+
+#### Parameters
+
+##### uid
+
+`string`
+
+The uid of the access control list to verify against.
+
+##### user
+
+`JWTUser` \| `undefined`
+
+The user to validate.
+
+##### req
+
+`HttpRequest`
+
+The request whose URL path and method will be verified.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+***
+
+### findACL()
+
+> **findACL**(`entityId`, `parentUids?`): `Promise`\<[`AccessControlList`](../interfaces/AccessControlList.md) \| `null`\>
+
+Defined in: [src/security/ACLUtils.ts:195](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L195)
+
+Retrieves the access control list with the associated identifier and populates the parent(s).
+
+#### Parameters
+
+##### entityId
+
+`string`
+
+The unique identifier of the ACL to retrieve.
+
+##### parentUids?
+
+`string`[] = `[]`
+
+The list of already found parent UIDs. This is used to break circular dependencies.
+
+#### Returns
+
+`Promise`\<[`AccessControlList`](../interfaces/AccessControlList.md) \| `null`\>
+
+***
+
+### getRecord()
+
+> **getRecord**(`acl`, `user`): [`ACLRecord`](../interfaces/ACLRecord.md) \| `null`
+
+Defined in: [src/security/ACLUtils.ts:459](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L459)
+
+Retrieves the first available record in the provided ACL associated with the provided user.
+
+#### Parameters
+
+##### acl
+
+[`AccessControlList`](../interfaces/AccessControlList.md)
+
+The access control list that will be searched.
+
+##### user
+
+`JWTUser` \| `undefined`
+
+The user to find a record for.
+
+#### Returns
+
+[`ACLRecord`](../interfaces/ACLRecord.md) \| `null`
+
+The ACL record associated with the given user if found, otherwise `undefined`.
+
+***
+
+### hasPermission()
+
+> **hasPermission**(`user`, `acl`, `action`): `Promise`\<`boolean`\>
+
+Defined in: [src/security/ACLUtils.ts:127](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L127)
+
+Validates that the user has permission to perform the provided action using the given access control list.
+
+#### Parameters
+
+##### user
+
+`JWTUser` \| `undefined`
+
+The user to validate permissions of.
+
+##### acl
+
+`string` \| [`AccessControlList`](../interfaces/AccessControlList.md)
+
+The ACL or uid of an ACL to validate permissions against.
+
+##### action
+
+[`ACLAction`](../enumerations/ACLAction.md)
+
+The action that the user desires permission for.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the user has at least one of the permissions granted for the given entity, otherwise `false`.
+
+***
+
+### populateParent()
+
+> **populateParent**(`acl`, `parentUids?`): `Promise`\<`void`\>
+
+Defined in: [src/security/ACLUtils.ts:479](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L479)
+
+Attempts to retrieve the parent access control list for the given ACL object.
+
+#### Parameters
+
+##### acl
+
+[`AccessControlList`](../interfaces/AccessControlList.md)
+
+The access control list whose parents will be populated.
+
+##### parentUids?
+
+`string`[] = `[]`
+
+The list of already found parent UIDs. This is used to break circular dependencies.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### removeACL()
+
+> **removeACL**(`uid`): `Promise`\<`void`\>
+
+Defined in: [src/security/ACLUtils.ts:247](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L247)
+
+Deletes the ACL with the given identifier from the database.
+
+#### Parameters
+
+##### uid
+
+`string`
+
+The unique identifier of the ACL to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### saveACL()
+
+> **saveACL**(`acl`): `Promise`\<[`AccessControlList`](../interfaces/AccessControlList.md) \| `null`\>
+
+Defined in: [src/security/ACLUtils.ts:333](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L333)
+
+Stores the given access control list into the ACL database.
+
+#### Parameters
+
+##### acl
+
+[`AccessControlList`](../interfaces/AccessControlList.md)
+
+The ACL to store.
+
+#### Returns
+
+`Promise`\<[`AccessControlList`](../interfaces/AccessControlList.md) \| `null`\>
+
+Returns the ACL that was stored in the database.
+
+***
+
+### saveDefaultACL()
+
+> **saveDefaultACL**(`acl`): `Promise`\<[`AccessControlList`](../interfaces/AccessControlList.md) \| `null`\>
+
+Defined in: [src/security/ACLUtils.ts:399](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/security/ACLUtils.ts#L399)
+
+Stores the given default access control list into the ACL database. A default ACL is a special type of ACL
+that is primarily defined and maintained within the code but allows for user-specific overrides. To accomplish
+this, the provided ACL is split in two. A new record is automatically created with the `uid` of the form
+`default_<uid>` that stores the exact record as provided by code. Then a second ACL record is created
+with the `uid` being that of what is passed as the argument. This second ACL is used to store user-defined
+overrides. As the `default_<uid>` record is always overwritten with the lastest version of the code, any
+user-defined changes made to it are lost on service restart.
+
+#### Parameters
+
+##### acl
+
+[`AccessControlList`](../interfaces/AccessControlList.md)
+
+#### Returns
+
+`Promise`\<[`AccessControlList`](../interfaces/AccessControlList.md) \| `null`\>

package/docs/reference/classes/AdminRoute.md

@@ -0,0 +1,51 @@
+[**@rapidrest/service-core**](../README.md)
+
+***
+
+[@rapidrest/service-core](../globals.md) / AdminRoute
+
+# Class: AdminRoute
+
+Defined in: [src/routes/AdminRoute.ts:50](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/routes/AdminRoute.ts#L50)
+
+The `AdminRoute` provides a default `/admin` endpoint that gives trusted users the following abilities:
+
+* Clear cache via `GET /admin/clear-cache`
+* Live tail the service logs via `GET /admin/logs`
+* Retrieve service dependencies via `GET /admin/dependencies`
+* Retrieve service release notes via `GET /admin/release-notes`
+* Restart the service via `GET /admin/restart`
+
+## Author
+
+Jean-Philippe Steinmetz
+
+## Constructors
+
+### Constructor
+
+> **new AdminRoute**(`releaseNotes`): `AdminRoute`
+
+Defined in: [src/routes/AdminRoute.ts:82](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/routes/AdminRoute.ts#L82)
+
+Constructs a new `ReleaseNotesRoute` object with the specified defaults.
+
+#### Parameters
+
+##### releaseNotes
+
+`string`
+
+The ReleaseNotes specification object to serve.
+
+#### Returns
+
+`AdminRoute`
+
+## Properties
+
+### cacheClient?
+
+> `protected` `optional` **cacheClient?**: `Redis`
+
+Defined in: [src/routes/AdminRoute.ts:55](https://github.com/rapidrest/service-core/blob/c8974caa9b5d3eb225bcbcd93945f2e588fe2f0a/src/routes/AdminRoute.ts#L55)