@restlessness/core

Core package for the restlessness framework

Documentation

Classes:

• AddOnPackage
• AuthorizerPackage
• DaoPackage
• EnvFile
• EnvironmentHandler
• JsonAuthorizers
• JsonConfigFile
• JsonDaos
• JsonEndpoints
• JsonEnvs
• JsonModels
• JsonSchedules
• PackageJson
• PathResolver
• ResponseHandler

AddOnPackage

Base class for Addon packages. It defines project's lifecycle hooks.

Methods

• static load<T>(packageName: string): T
  Require packageName from the project's node_modules folder
  Returns: the loaded package

• abstract postInstall(): Promise<void>
  Post install hook. The CLI commands add-auth and add-dao execute this method. Use it to add the addon to the project and to perform initialization operations (for example it is possible to add required environment variables to the existing environment).

• abstract postEnvCreated(envName: string): Promise<void>
  Post environment created hook. Called after a new environment has been created. Use it to define environment variables needed by the addon.

• abstract beforeEndpoint<T>(event: AWSLambda.APIGatewayProxyEventBase<T>, context: AWSLambda.Context): Promise<void>
  Before endpoint hook. Called before executing the endpoint handler. It receives the handler's parameters, event and context objects, see @types/aws-lambda for details.

• abstract beforeSchedule<T>(event: AWSLambda.ScheduledEvent | T, context: AWSLambda.Context): Promise<void>
  Before schedule hook. Called before executing the schedule handler. It receives the schedule's parameters, event and context objects, see @types/aws-lambda for details.

Example

These Addon packages provided by Restlessness can be taken as example:

• @restlessness/auth-cognito
• @restlessness/auth-jwt
• @restlessness/dao-mongo

AuthorizerPackage

Base class for Authorizer Addons, extension of AddOnPackage.

Methods

• abstract createToken(session: SessionModelInstance): Promise<string>
  session: the session to be embedded into the token
  Returns: the token string

• abstract verifyToken(event: AuthorizerEvent): Promise<AuthorizerResult>
  Grant or refuses authorization based on the token contained in the event
  event: AuthorizerEvent
  Returns: an AuthorizerResult

• abstract parseSession(session: string): Promise<unknown>
  session: the serialized session
  Return: the deserialized session object

• abstract getSessionModelName(): string
  Returns: the name of the exported model class

• abstract getSessionModelImport(): string
  Returns: import statement string to import the exported model class

• async authorizer(event: AuthorizerEvent): Promise<AuthPolicyResponse>
  The function entry point that will be exported and used by lambda functions. It verifies the request token and returns the auth policy accordingly
  event: AuthorizerEvent
  Returns: AuthPolicyResponse

• generatePolicy(event: AuthorizerEvent, authResult: AuthorizerResult): AuthPolicyResponse
  Generate an auth policy based on the event, and the auth result.
  event: AuthorizerEvent
  Returns: AuthPolicyResponse

Types

AuthorizerEvent

see aws doc for details

interface AuthorizerEvent {
  headers?: { [key: string]: string },
  pathParameters?: { [name: string]: string } | null,
  queryStringParameters?: { [name: string]: string } | null,
  authorizationToken?: string,
  methodArn?: string,
  type: 'TOKEN' | 'REQUEST'
}

AuthorizerResult

interface AuthorizerResult {
  granted: boolean,
  serializedSession?: string,
  principalId?: string,
}

AuthPolicyResponse

interface AuthPolicyResponse {
  principalId: string,
  policyDocument: any,
  context?: any,
}

Example

• @restlessness/auth-cognito
• @restlessness/auth-jwt

DaoPackage

Base class for Data Access Object Addons, extension of AddOnPackage.

Methods

• abstract modelTemplate(modelName: string): string
  modelName: name of the model to be created
  Returns: the code template for the model

EnvFile

Class to manage environment files.

Methods

• constructor(envName: string)
  envName: name of the environment to manage

• getValue(key: string): Promise<string>
  Returns: the env value corresponding to key

• setValue(key: string, value: string, overwrite: boolean = false): Promise<void>
  Set value for key
  overwrite: replace the value if it already exists

• setParametricValue(key: string): Promise<void>
  Set a key as parametric, based on the environment name.
  The generated entry is key=${key_ENVNAME}

• expand(): Promise<ENV>
  Returns: the environment object with parametric values expanded

• generate(): Promise<void>
  Generate the .env file in the project root, with parametric values expanded

EnvironmentHandler

Load environment variables once.

Methods

• load(): void
  Load .env file into process.env, if the RLN_ENVIRONMENT_LOADED variable isn't set, and update it accordingly.

JsonAuthorizers

Implementation of JsonConfigFile for authorizers config file.

Types

JsonAuthorizersEntry

interface JsonAuthorizersEntry extends JsonConfigEntry {
  name: string
  package: string     // corresponding package under node_modules folder
  shared: boolean     // shared, can be used across services if true
  importKey?: string  // key for importing the authorizer from other services
}

JsonConfigFile

Base abstract class to handle json configuration files, composed by list of entries.

Fields

• entries: T[]
  List of configuration entries

Methods

• abstract get jsonPath(): string
  Returns: the path of the configuration file

• read(): Promise<void>
  Read the configuration file and save it into the entries field

• write(): Promise<void>
  Save the list of entries into the file specified by the jsonPath getter

• getEntryById(id: string): Promise<T>
  Returns: the corresponding entry or null

• addEntry(entry: T): Promise<void>
  Add entry to the list of entries, throw an error if the entry already exists

• removeEntryById(id: string): Promise<void>
  Remove the corresponding entry

• updateEntry(entry: T): Promise<void>
  Update the entry, throw an error if an entry with that id does not exist

Types

JsonConfigEntry

interface JsonConfigEntry {
  id: string
}

JsonDaos

Implementation of JsonConfigFile for data access objects config file.

Types

JsonDaosEntry

interface JsonDaosEntry extends JsonConfigEntry {
  name: string
  package: string
}

JsonEndpoints

Implementation of JsonConfigFile for endpoints config file.

Methods

• create(endpoint: { routePath: string, method: HttpMethod, authorizerId?: string, daoIds?: string[], warmupEnabled?: boolean, serviceName: string }): Promise<JsonEndpointsEntry>
  Creates an endpoint entry, file templates (handler, validation and test). Creates the associated lambda function on the corresponding serverless service file.

Types

JsonEndpointsEntry

interface JsonEndpointsEntry extends JsonConfigEntry {
  route: string
  safeFunctionName: string
  description?: string
  method: HttpMethod
  authorizerId?: string
  daoIds?: string[]
  warmupEnabled: boolean
  serviceName: string
}

enum HttpMethod {

enum HttpMethod {
  GET = 'get',
  POST = 'post',
  DELETE = 'delete',
  PUT = 'put',
  PATCH = 'patch'
}

JsonEnvs

Implementation of JsonConfigFile for environments config file.

Methods

• create(id: string): Promise<JsonEnvsEntry>
  Creates the environment and execute the postEnvCreated hook

Types

JsonEnvsEntry

interface JsonEnvsEntry extends JsonConfigEntry {
  type: EnvType
  stage?: EnvStage
}

JsonModels

Implementation of JsonConfigFile for models config file.

Methods

• create(id: string, daoId?: string, template?: string): Promise<JsonModelsEntry>
  Creates a new model entry, and creates a file template for the model id: model's id
  daoId: associated data access object, if specified its model template will be used
  template: use a custom model template

Types

JsonModelsEntry

interface JsonModelsEntry extends JsonConfigEntry {
  daoId?: string
}

JsonSchedules

Implementation of JsonConfigFile for schedules config file.

Methods

• createSchedule(event: Event): Promise<JsonSchedulesEntry>
  Creates a schedule event function, see serverless doc for details.

Types

Event

interface Event {
    name: string
    description?: string
    rateNumber: number
    rateUnit: RateUnit
    enabled?: boolean
    serviceName: string
    input?: {
      type: 'input' | 'inputPath' | 'inputTransformer'
      value: { [key: string]: any }
    },
    daoIds?: string[]
}

JsonSchedulesEntry

interface JsonSchedulesEntry extends JsonConfigEntry {
  description?: string
  rateNumber: number
  rateUnit: RateUnit
  enabled?: boolean
  serviceName: string
  input?: {
    type: 'input' | 'inputPath' | 'inputTransformer'
    value: { [key: string]: any }
  }
  safeFunctionName: string
  daoIds?: string[]
}

RateUnit

enum RateUnit {
  MINUTES = 'minute',
  HOURS = 'hour',
  DAYS = 'day',
}

PackageJson

Manage package.json file.

Methods

• static read(): Promise<any>
  Returns: the parsed Json object

• static merge(obj): Promise<void>
  Merge package.json content with the input obj

• static removeAtPath(objPath: string): Promise<void>
  Remove the specified objPath from the package.json. objPath uses lodash syntax

• static write(packageJson): Promise<void>
  Write the input packageJson object into the package.json file

PathResolver

Utility class to resolve path of common files and folders.

Methods

• static get getPrjPath(): string

• static get getPackageJsonPath(): string

• static get getServicesJsonPath(): string

• static get getSharedResourcesServerlessJsonPath(): string

• static get getOfflineServerlessJsonPath(): string

• static get getEnvsPath(): string

• static get getConfigsPath(): string

• static get getAuthorizersConfigPath(): string

• static get getEnvsConfigPath(): string

• static get getModelsConfigPath(): string

• static get getEndpointsConfigPath(): string

• static get getSchedulesConfigPath(): string

• static get getDaosConfigPath(): string

• static get getDefaultHeadersConfigPath(): string

• static get getNodeModulesPath(): string

• static get getDistPath(): string

• static get getDeployPath(): string

• static get getSrcPath(): string

• static get getEndpointsPath(): string

• static get getDistEndpointsPath(): string

• static get getSchedulesPath(): string

• static get getDistSchedulesPath(): string

• static get getModelsPath(): string

• static get getAuthorizersPath(): string

ResponseHandler

Utility methods for creating handler functions responses.

Methods

• static json(response, statusCode: StatusCodes = StatusCodes.OK, options?: ResponseOptions): Response
  Creates a Json response object

• static buffer(data: Buffer, statusCode: StatusCodes = StatusCodes.OK, options?: ResponseOptions): Response
  Creates response object with data encoded in base64

Types

Response

interface Response {
  statusCode: number,
  body: string,
  headers?: HttpHeader
  isBase64Encoded?: boolean
}

ResponseOptions

interface ResponseOptions {
  headers?: {
    [key: string]: string
  },
}