Function: httpServiceEntrypoint()

httpServiceEntrypoint(options?): EntrypointAdapter<ServiceContext<{ }>>

Create a service adapter of an entrypoint served over plain HTTP, handy to call the service actions from tools such as curl or Postman during development. It needs no optional dependency.

A request is a POST to the path whose JSON body holds the action's pattern and input ({"cmd": "echo", "text": "hi"}). The response is always 200 with the body {success, error, payload} (see ServiceResponseCodec): payload is the result, or error the whole error object when the action failed (no matching action, validation…). A body that is not JSON is answered with 400 and an error body, a body over limit with 413; any other method or path with 404. The CORS headers allow any origin.

The events pushed to the clients (Entrypoint.notify, Entrypoint.broadcast) are streamed as Server-Sent Events by GET <path>/events: each event's name is the SSE event, its arguments the JSON array of its data. A client gives its id in the id header or the id query parameter (at most 200 characters), the same on its requests so that they carry it as ServiceContext.clientId; without one, the stream assigns a random id, sent first as the client event. The streams receive a keep-alive comment every 15 seconds.

When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new requests are answered with an EntrypointStoppedException error; once the requests in progress end, the event streams are closed and the server shuts down, closing its remaining connections (the ones taken over by an upgrade of the application too).

Parameters

options?

HTTPServiceEntrypointOptions

The adapter options; by default it listens on port 3000 of all the interfaces, on the path /.

Returns

EntrypointAdapter<ServiceContext<{ }>>

The adapter, to give to the service option of buildEntrypoints.

Example

import {Application} from 'lakutata'
import {buildEntrypoints, Controller, httpServiceEntrypoint} from 'lakutata/com/entrypoint'
import {ServiceAction} from 'lakutata/decorator/ctrl'

class EchoController extends Controller {
    @ServiceAction({cmd: 'echo'})
    public async echo(input: {text: string}): Promise<string> {
        return input.text
    }
}

Application.run({
    id: 'echo.service',
    name: 'Echo',
    components: {
        entrypoint: buildEntrypoints({
            controllers: [EchoController],
            service: httpServiceEntrypoint({port: 3000, path: '/rpc'})
        })
    },
    bootstrap: ['entrypoint']
})

//A client: the response is {"success": true, "error": null, "payload": "hi"}
const response: Response = await fetch('http://localhost:3000/rpc', {
    method: 'POST',
    headers: {'Content-Type': 'application/json', 'id': 'client-1'},
    body: JSON.stringify({cmd: 'echo', text: 'hi'})
})
console.log(await response.json())
//The events pushed to client-1: GET http://localhost:3000/rpc/events?id=client-1 (text/event-stream)