Add pre- and post-hooks (#271)

Author: Marc

.markdownlint.yml

@@ -0,0 +1,3 @@
+"line-length": false
+"no-duplicate-heading":
+  siblings_only: true

CHANGELOG.md

@@ -5,35 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [0.5.0] - 2022-06-07
+## [Unreleased]
 
 ### Added
 
 - Added mappings for 'id' and 'collection' for default sort keys
-
-## [0.5.0] - 2022-06-01
+- Added STAC_API_VERSION as an environment variable to the serverless.yml file
+- Added STAC_API_VERSION to display on the API landing page within the api.js file under src/lib/api.js in the collectionsToCatalogLinks function
+- Add support for pre- and post-hooks
 
 ### Changed
 
 - Modified sortby and collections parameters in nextlink
-
-## [0.5.0] - 2022-05-20
-
-### Changed
-
 - Used map instead of foreach/push in api.js file
-
-## [0.5.0] - 2022-05-18
-
-### Added
-
-- Added STAC_API_VERSION as an environment variable to the serverless.yml file
-- Added STAC_API_VERSION to display on the API landing page within the api.js file
-under src/lib/api.js in the collectionsToCatalogLinks function
-
-### Changed
-
 - Changed the rel type to 'server' for the URL to the STAC API webpage inside the Links object
+- Modified sortby and collections parameters in nextlink
+- Used map instead of foreach/push in api.js file
+- Compression of responses is now handled by API Gateway and not Express. This means that the _uncompressed_ response from stac-server [must be less than 6 MB](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#function-configuration-deployment-and-execution).
 
 ### Removed
 

README.md

@@ -19,6 +19,7 @@
     - [Ingesting large items](#ingesting-large-items)
     - [Subscribing to SNS Topics](#subscribing-to-sns-topics)
     - [Ingest Errors](#ingest-errors)
+  - [Pre- and Post- Hooks](#pre--and-post-hooks)
   - [Development](#development)
     - [Running Locally](#running-locally)
     - [Running Unit Tests](#running-unit-tests)
@@ -381,6 +382,51 @@ Stac-server can also be subscribed to SNS Topics that publish complete STAC Item
 
 Errors that occur during ingest will end up in the dead letter processing queue, where they are processed by the `stac-server-<stage>-failed-ingest` Lambda function. Currently all the failed-ingest Lambda does is log the error, see the CloudWatch log `/aws/lambda/stac-server-<stage>-failed-ingest` for errors.
 
+## Pre- and Post-Hooks
+
+Stac-server supports two hooks into the request process: a pre-hook and a post-hook. These are each lambda functions which, if configured, will be invoked by stac-server. It is assumed that the stac-server lambda has been granted permission to invoke these lambda functions, if configured.
+
+### Pre-Hook
+
+If the stac-server is deployed with the `PRE_HOOK` environment variable set to the name of a lambda function, then that function will be called as the pre-hook.
+
+The event passed into the pre-hook lambda will be an instance of an [API Gateway Proxy Event](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format).
+
+If the return value from the pre-hook lambda is an instance of an [API Gateway Proxy Result](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format), then that response will immediately be returned to the client.
+
+If the return value of the pre-hook lambda is an instance of an [API Gateway Proxy Event](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format), then that event will be passed along to stac-server.
+
+If the pre-hook lambda throws an exception, an internal server error will be returned to the client.
+
+### Post-Hook
+
+If the stac-server is deployed with the `POST_HOOK` environment variable set to the name of a lambda function, then that function will be called as the post-hook.
+
+The event passed into the post-hook labmda will be the response from the stac-server, and will be an instance of an [API Gateway Proxy Result](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format).
+
+The return value of the post-hook lambda must be an instance of an [API Gateway Proxy Result](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-output-format).
+
+If the post-hook lambda throws an exception, an internal server error will be returned to the client.
+
+### Request Flow
+
+```mermaid
+flowchart
+  client -- APIGatewayProxyEvent --> pre-hook
+  pre-hook[pre-hook lambda]
+  pre-hook -- APIGatewayProxyResult --> client
+  pre-hook -- APIGatewayProxyEvent --> stac-server
+  post-hook[post-hook lambda]
+  stac-server -- APIGatewayProxyResult --> post-hook
+  post-hook -- APIGatewayProxyResult --> client
+```
+
+### Notes
+
+Lambda payloads and responses [must be less than 6 MB](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#function-configuration-deployment-and-execution). A larger payload will result in an internal server error being returned to the client.
+
+The outputs of the pre- and post-hooks are validated and, if they don't comply with the defined schemas, an internal server error will be returned to the client. Information about the invalid event, as well as details about the parsing errors, will be logged to CloudWatch.
+
 ## Development
 
 Install [NVM](https://github.com/nvm-sh/nvm) to manage your Node.js environment.