HTTP Server Stage

This stage provides the ability for other processes to connect with your pipeline to retrieve status information, or more importantly, to subscribe to publishers or send commands to subscribers.

Configuration

The provided ark::comms::HttpServerStageConfig structure allows you to configure the web server.

It has the following top-level parameters:

  • listen_address - The IPv4 address that it listens on (“0.0.0.0:8080” by default)
  • maximum_receive_buffer_size - Per-connection incoming (PUT) message limit
  • maximum_write_buffer_size - Per-connection outgoing (GET/websocket) buffer size
  • maximum_open_requests - Limit of simultaneous open sockets (requests or websockets)

The latter three parameters allow you to bound the number of connections or memory usage of the comms stack, trading off support for slower links or larger message sizes against memory usage.

There are also two parameters for controlling access:

  • publisher_access
  • subscriber_access

Both of these have an allow list/block list member that allows you to define which channels you wish to be exported. By default, all channels are exported.

By populating the allow list, you restrict the channels exported to be just the items in the allow list. The block list takes further precedence, blocking anything that is contained in that list.

Command Line

You can configure this stage on the command line as well, with two options:

  • disable-http-server - Prevent HTTP server from starting
  • http-server-address - Run on an alternate address/port

Disabling the HTTP server may improve overall performance of your pipeline, but you will not be able to access it via HTTP. It will also avoid warning messages if running multiple pipelines on the same address/machine.

Interacting

The stage will automatically subscribe to any publisher in the system, and will expose that over HTTP under two paths:

  • /<channel_name> - The raw bitstream.
  • /<channel_name>/json - JSON-encoded versions of the messages.

These are websockets, and they publish data as messages are published.

If you want to just retrieve the latest message using standard HTTP, you can with these APIs:

  • /<channel_name>/latest - The latest message (raw bitstream).
  • /<channel_name>/latest/json - The latest message (JSON-encoded).

The stage will also automatically create HTTP paths for subscribers. Unlike publishers, these are just HTTP REST endpoints. These can consume bitstream (rbuf-encoded) messages:

  • /<channel_name>/publisher - Consumes raw (rbuf-encoded) bitstream messages.
  • /<channel_name>/publisher/json - Consumes JSON-encoded messages.

Writing an rbuf-encoded message to this URL will cause it to be published, and all of your subscribers will receive that message.

Finally, there are a few built-in URLs:

  • <channel_name>/schema_registry - provides the schema for a channel
  • <channel_name>/type_name - provides the C++ typename for the channel
  • /publishers - lists all of the publishers in the system
  • /publishers/serializable - lists all of the publishers and their schemas in the system
  • /subscribers - lists all of the subscribers in the system
  • /server/instance - server-specific instance information (a unique GUID)

The list of publishers/subscribers is restricted by the visibility/access control lists defined via configuration.

Optional extensions are provided to enable compression. We do not currently support the websocket-standardized deflate compression, but we do support LZ4 and Zstd compression by setting the x-permessage-lz4 or x-permessage-zstd extension.

Metrics

There are no metrics for this stage.