Skip to main content

Lifecycle

The Bigsby request lifecycle is composed of a number of stages that revolve around validation, parsing, authentication, execution and error handling.

Request Lifecycle

Hooks​

Bigsby exposes hooks that enable the creation of complex and powerful request workflows.

  • Each hook accepts an array of functions known as HookChains.
  • Hooks can optionally return a HookResult which includes a ResponseBuilder.
  • Each hook in the chain will receive the ResponseBuilder returned by the previous hook (unless it's immediate).
  • The resulting ApiResponse produced from the ResponseBuilder at the end of the chain will be returned as the handler's response.

Hooks can be used to perform special startup or shutdown operations, transform request/response payloads, or add data to the request state.

tip

All hooks are asynchronous, they're called in the order they appear in the input array, and they receive the RequestContext of the invocation (some hooks receive additional inputs too, see below).

const bigsby = new Bigsby({
  api: {
    lifecycle: {
      onRequestInvalid: [addErrorPayload]
    }
  }
});

async function addErrorPayload({ error }: OnRequestInvalidInputs): Promise<HookResult> {
  if (error instanceof ValidationError) {
    return {
      immediate: true,
      response: new ResponseBuilder({
        code: "INVALID_REQUEST",
        message: "The request is invalid.",
        details: error.details.map(({message}) => message)
      }).statusCode(400);
    };
  }
}

onInit​

The onInit hook chain is called a single time when the Lambda handler instance is first invoked, before any other stage in the lifecycle. It receives the Bigsby instance the hook is registered; it cannot immediate the response.

preInvoke​

The preInvoke hook chain is called before any other stage in the lifecycle, on each invocation of the handler.

preAuth​

The preAuth hook chain is called immediately prior to any authenticator or AuthScheme attached to a handler. If no authentication is attached to the handler, it won't be called.

onAuthFail​

The onAuthFail hook chain is called when a request fails authentication. In addition to the request context, it receives the Error thrown by the authenticator.

preValidate​

The preValidate hook chain is called immediately prior to request validation. If no request validation is attached to the handler, it won't be called.

preParse​

The preParse hook chain is called immediately prior to processing the incoming API Gateway event payload, including the execution of any event parsing instructions.

onRequestInvalid​

The onRequestInvalid hook chain is called in two scenarios:

  • The Joi request schema validation fails.
  • Parsing the API Gateway event fails.

In addition to the request context, the hook receives either the ValidationError generated by Joi, or the RequestParseError generated by Bigsby.

preExecute​

The preExecute hook chain is called immediately prior to the invoke method of the handler class being called.

preResponse​

The preResponse hook chain is called immediately prior to Bigsby returning a response, during an invocation that is returning normally. In addition to the request context, it receives the ApiResponse object representing the outgoing response.

onResponseInvalid​

The onResponseInvalid hook chain is called in two scenarios:

  • The Joi response schema validation fails.
  • An error occurred when Bigsby attempted to create the ApiResponse from the handler's return value.

In addition to the request context, the hook receives either the ValidationError returned by Joi, or the TypeCoercionError generated by Bigsby.

info

Response schema validation errors are considered internal errors because they indicate a breaking change to the response contract. Bigsby errors during creation of an ApiResponse are also considered internal errors. Because of this, the onError hook will be called after onResponseInvalid.

onError​

The onError hook chain is called when an unhandled exception occurs during the execution of the handler, or after a hook chain that isn't expected to reject, rejects a value.

Immediate Response​

Hooks (except onInit) can 'takeover' a handler's response by optionally returning a HookResultwith the immediate option. The handler will discontinue the request lifecycle and immediately return the response when this flag is specified.

Response Takeover