PoHTTP: Parcel Delivery over HTTP
- Id: RS-007.
- Status: Working draft.
- Type: Implementation.
This document describes PoHTTP, a parcel delivery binding for external Parcel Delivery Connections (PDC) based on HTTP.
Table of contents
- Binding hint
- Parcel Delivery
- HTTP Considerations
- TLS Considerations
- Relevant Specifications
- Open Questions
PoHTTP was specifically designed to make it easier for maintainers of existing systems to support Relaynet. For example, an organization maintaining a REST API could collect parcels by implementing a new API endpoint (e.g.,
/relaynet), or they could integrate an Enterprise Service Bus to convert Relaynet service messages to API calls.
In some cases, it may also be desirable for a relaying gateway to expose an HTTP interface so it can receive parcels from certain endpoints. For example, a Shell script in a legacy system could use
curl to deliver parcels.
As an external PDC, the only operation supported by this binding is parcel delivery.
The hint for this binding MUST be
http. For example,
rne+http://api.example.com/relaynet would be a valid public endpoint address and it would correspond to the HTTP URL
https://api.example.com/relaynet (note the
To deliver each parcel, the client MUST make a
POST request to the HTTP URL corresponding to the node address, with
application/vnd.relaynet.parcel as the content type and the parcel as the body. If the client is a relaying gateway, it MUST provide the target endpoint with its address using the request header
X-Relaynet-Gateway. For example,
The server MUST respond with one of the following status codes:
202(Accepted) response as soon as it successfully stores or forwards the parcel.
307(Temporary Redirect) per RFC-7231 or
308(Permanent Redirect) per RFC-7238, in which case the client MUST repeat the
POSTrequest against the specified URL.
- Any other standard status code in the range 400-599 that the server regards applicable.
- A relaying gateway MAY return a
507(Insufficient Storage) response when it no longer has the capacity to accept parcels for the target endpoint or its gateway.
Clients and servers implementing this specification MUST support HTTP version 1.1, and they SHOULD also support HTTP version 2.
Rate limiting SHOULD be supported by clients as servers MAY use it.
Headers other than the ones described in this specification MAY be used, but defining how they should be handled at the other end is outside the scope of this specification.
Since message transport bindings MAY NOT use TLS when communication happens via the loopback network interface per Relaynet Core, clients MUST fall back to plain HTTP without TLS in that case if the server does not support TLS. This constraint also applies to redirects.
Server Name Identification MUST be supported by clients and MAY be used by servers.
- This is basically a webhook. Should it be renamed to PoWebhook?