https://github.com/somod-dev/somod-http-extension
somod extension to validate and parse http event
https://github.com/somod-dev/somod-http-extension
Last synced: 3 days ago
JSON representation
somod extension to validate and parse http event
- Host: GitHub
- URL: https://github.com/somod-dev/somod-http-extension
- Owner: somod-dev
- License: mit
- Created: 2023-05-02T06:09:17.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-12-27T10:10:20.000Z (3 months ago)
- Last Synced: 2025-12-28T22:44:14.953Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 225 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SOMOD Http Extension
---
The [SOMOD](https://somod.dev) Extension Configure HTTP routes and validate incoming HTTP Requests in Serverless Functions.
> The middlware in this extension works with Functions of type `HttpApi` Only.
## Install
Install as an npm package in somod modules
```bash
npm install somod-http-extension
```
## Usage
### Attach the middleware to the Serverless Function
```yaml
Resources:
MyHttpHandler:
Type: AWS::Serverless::Function
Properties:
CodeUri:
SOMOD::Function:
# ...
middlewares:
- module: somod-http-extension
resource: SomodHttpMiddleware
# ...
```
Refer to SOMOD's [Middleware](https://docs.somod.dev/reference/main-concepts/serverless/middlewares) reference for more information
### Configure Routes and Schemas
Routes configuration for each serverless function can be provided using a yaml file at `serverless/functions/.http.yaml`.
Example:
```yaml
# serverless/functions/user.http.yaml
/user/{userId}:
GET:
parameters:
- in: path
name: userId
schema:
type: string
maxLength: 32
required: true
POST:
parameters:
- in: path
name: userId
schema:
type: string
maxLength: 32
required: true
body:
parser: json
schema:
type: object
required: [name]
properties:
name:
type: string
maxLength: 32
email:
type: string
format: email
```
### Access Sanitized Request
The sanitized request can be accessed using the [middleware](https://docs.somod.dev/reference/main-concepts/serverless/middlewares)'s context using the **`somod-http-request`** key.
Example:
```typescript
// serverless/functions/user.ts
const UserService = event => {
const request = event.somodMiddlewareContext.get("somod-http-request");
// use request to read the data from the incoming http request
};
export default UserService;
```
This module also provides a utility library to create Serverless Functions with multiple routes easily. Refer to [RouteBuilder](#routeBuilder) for more details
## Specification
### Structure of Routes configuration file
In general, routes configuration in `.http.yaml` file follows the below structure
```yaml
:
:
parameters?:
- in: <"path", "query" or "header">
name:
schema:
required:
body?:
parser?: <"text"|"json"|"formdata">. If not provided, automatically choosen based on the Content-Type Header (text is considered if automatic detection fails)
schema:
```
The complete JSONSchema is available [here](/lib/routes-schema.ts)
### Type of the Request object
The request object accessed using `event.somodMiddlewareContext.get("somod-http-request")` has this type.
```typescript
type Request<
T = unknown,
PT extends Record = Record,
QT extends Record = Record,
HT extends Record = Record
> = {
route: string;
method: string;
parameters: {
path: PT;
query: QT;
header: HT;
};
body: T;
};
```
The `Request` Type is available from this module to use (import as shown below)
```typescript
import { Request } from "somod-http-extension";
```
### HTTP Error Types
The validation middleware returns the following HTTP error codes
- `404` - When the method and path in the incoming http request do not match any of the configured routes.
- `400` - When the parsing or validating of the incoming request fails (following the configuration in `.http.yaml`).
- `500` - Any other failures.
## RouteBuilder
The `RouteBuilder` is a wrapper javascript utility library to create serverless functions with multiple routes.
### Using the RouteBuilder
```typescript
// serverless/function/user.ts
import { RouteBuilder } from "somod-http-extension";
const builder = new RouteBuilder();
builder.add("/user/{userId}", "get", getUserFunction);
builder.add("/user/{userId}", "post", updateUserFunction);
export default builder.getHandler();
```
### RouteBuilder Specification
RouteBuilder has 2 methods
- `add`
```typescript
function add(
path: string,
method: string,
handler: (request: Request, event: RawEvent) => Promise
): void {
//
}
```
The handler receives the [sanitized request object](#type-of-the-request-object) and the raw event from AWS. The handler has to return a promise which resolves to the Response object.
> The Raw Event type and Response type is documented [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html) in the AWS specification.
> This module works with HTTP Payload format version 2.0 only
- `getHandler`
```typescript
function getHandler(): (event: RawEvent) => Promise {
//
}
```
handle function returns the function which is a lambda function handler
## Issues
The project issues, features, and milestones are maintained in this GitHub repo.
Create issues or feature requests at https://github.com/somod-dev/somod-http-extension/issues
## Contributions
Please read our [CONTRIBUTING](https://github.com/somod-dev/somod/blob/main/CONTRIBUTING.md) guide before contributing to this project.