@selfage/service_handler/README.md

Http-based service handlers on top of expressjs.

# @selfage/service_handler

## Install

`npm install @selfage/service_handler`

## Overview

Written in TypeScript and compiled to ES6 with inline source map & source. See [@selfage/tsconfig](https://www.npmjs.com/package/@selfage/tsconfig) for full compiler options. Provides a runtime lib to hook service handlers, generated by `@selfage/generator_cli` and implemented by you, onto `Express.js`.

## Example usage

In this repo, `test_data/get_comments.ts`, `test_data/get_history.ts`, and `test_data/upload_file.ts` are code presumbaly generated by `@selfage/generator_cli`.

`base_handler_test.ts` contains all sample use cases on how to register handlers, and how to implement handlers, including handle authentication and streaming bytes.

## CORS & preflight handler

Allowing CORS for all domains is an opinionated decision that restricting CORS doesn't help account/data security at all, but might annoy future development. We should guarantee security by other approaches.

Before making any cross-site request, browsers might send a preflight request to ask for valid domain/site. We provide a simple preflight handler to allow all sites.

```TypeScript
import express = require('express');
import { HandlerRegister } from '@selfage/service_handler/register';

let app = express();
new HandlerRegister(app).registerCorsAllowedPreflightHandler();
```

## Sign a session string

You have to configure your secret key for signing at the startup of your server, i.e., a secret key for sha256 algorithm. Please refer to other instructions on the best practice of generating a secret key and storing it.

```TypeScript
import { SessionSigner } from '@selfage/service_handler/session_signer';

SessionSigner.SECRET_KEY = 'Configure a secrect key';
// Configure routing and start server.
```

Then you can build a signed session as below.

```TypeScript
import { SessionBuilder } from '@selfage/service_handler/session_signer';

let signedSession = SessionBuilder.create().build(JSON.stringify({sessionId: '1234', userId: '5678'}));
```

## Session expiration

Regardless of the data structure of your session, the signed session string always contains the timestamp when signing. By default, a session is expired 30 days after the signing timestamp. You have to re-sign a session the same way as a new session and return it to the client to refresh the timestamp.

You can configure the session longevity as the following, usually before starting your server.

```TypeScript
import { SessionExtractor } from '@selfage/service_handler/session_signer';

SessionExtractor.SESSION_LONGEVITY = 30 * 24 * 60 * 60; // seconds
// Configure routing and start server.
```

## Request body size

We choose 1MiB or `1024*1024` bytes as the limit of the request body size, making the same assumption as Google's Datastore which imposes the same size limit for an entity.

There is no built-in limit on streaming bytes data.