@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 commandsadd-auth
andadd-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:
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
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 iskey=${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 intoprocess.env
, if theRLN_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 theentries
field -
write(): Promise<void>
Save the list of entries into the file specified by thejsonPath
getter -
getEntryById(id: string): Promise<T>
Returns: the corresponding entry ornull
-
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
},
}