Remote Bundle Wire Protocol

This document specifies the HTTP protocol used by SAPL nodes to fetch .saplbundle files from remote servers. Third-party servers can implement this protocol to serve bundles to SAPL nodes.

URL Convention

Bundles are addressed by convention:

{baseUrl}/{pdpId}

Example: https://pap.example.com/bundles/production

The pdpId is a path segment appended to the configured base URL. No query parameters are used.

Regular Polling

Request 

GET {baseUrl}/{pdpId} HTTP/1.1
Host: pap.example.com
If-None-Match: "v42-sha256-abc123"
Accept: application/octet-stream
Authorization: Bearer eyJhbGciOiJSUz...
Header Required Description
If-None-Match After first fetch ETag from the previous response. Omitted on first request.
Accept Yes Always application/octet-stream.
Auth header If configured Custom header name and value (e.g., Authorization: Bearer ...).

Response: Bundle Changed (200) 

HTTP/1.1 200 OK
Content-Type: application/octet-stream
ETag: "v43-sha256-def456"
Content-Length: 12345

<.saplbundle ZIP bytes>
Header Required Description
Content-Type Recommended Should be application/octet-stream. The client does not validate this header.
ETag Recommended Opaque version identifier. Used by the client for If-None-Match on subsequent requests.
Content-Length Recommended Size of the response body in bytes.

The response body is the raw .saplbundle ZIP archive bytes.

Response: Not Modified (304) 

HTTP/1.1 304 Not Modified
ETag: "v42-sha256-abc123"

The server returns 304 when the bundle has not changed since the ETag provided in If-None-Match. No response body is sent.

Long-Poll Mode

Long-poll uses the same request format as regular polling. The server behavior differs:

  1. If the bundle has changed since the provided ETag: respond immediately with 200 OK and the new bundle.
  2. If unchanged: hold the connection open until either:
    • The bundle changes: respond 200 OK with the new bundle.
    • The server’s hold timeout expires: respond 304 Not Modified.

The client reconnects immediately after receiving either response.

Server Timeout Advertisement (Optional)

Servers supporting long-poll MAY include an informational header:

X-Long-Poll-Timeout: 30

This indicates the maximum hold time in seconds. It is informational for client-side logging and diagnostics only. The client does not use this value to configure its own timeouts.

Error Responses

Status Meaning Client Behavior
200 Bundle returned Parse, verify signature, load configuration.
304 Not modified Keep current bundle, re-poll after interval.
301, 302, 307, 308 Redirect Follow redirect (if enabled in client config).
401, 403 Authentication failure Log error, retry with exponential backoff.
404 pdpId not found on server Log error, retry with exponential backoff.
5xx Server error Log error, retry with exponential backoff.

All error responses trigger retry with exponential backoff. The client never stops retrying. After the server recovers, the client resumes normal operation.

Bundle Format

The response body for 200 OK is a .saplbundle file: a ZIP archive containing:

  • pdp.json (required): PDP configuration including combining algorithm and configuration ID.
  • *.sapl files: SAPL policy documents.
  • MANIFEST.json (if signed): Cryptographic manifest with content hashes.
  • MANIFEST.json.sig (if signed): Ed25519 signature of the manifest.

See the SAPL bundle documentation for the full archive format specification.

Security Considerations

Transport Security

Servers SHOULD use HTTPS. The client supports TLS via standard Spring Boot SSL configuration.

Bundle Signatures

Bundles fetched over HTTP are verified using Ed25519 signatures by default. The signature verification is performed client-side using the public key configured on the node. This provides end-to-end integrity verification independent of transport security.

A server serving unsigned bundles to a client with mandatory signature verification will cause the client to reject the bundle and retry. The client never loads an unsigned bundle when signatures are required.

Authentication

The protocol supports a single configurable HTTP header for authentication. The header name and value are sent on every request. Common patterns:

Pattern Header Name Header Value
OAuth2 Bearer Token Authorization Bearer eyJhbGci...
Static API Key X-Api-Key sk-abc123...
Basic Auth Authorization Basic dXNlcjpwYXNz...

Implementing a Compatible Server

A minimal compatible server must:

  1. Serve .saplbundle ZIP files at {baseUrl}/{pdpId} with 200 OK.
  2. Keep bundle responses under 16 MB (the client rejects larger responses).
  3. Return 404 for unknown pdpIds.
  4. Optionally: support If-None-Match / ETag for conditional requests with 304 responses.

For long-poll support, the server must additionally:

  1. Hold the connection open when the bundle has not changed.
  2. Respond with 200 OK when the bundle changes during the hold.
  3. Respond with 304 Not Modified when the hold timeout expires.

Static file servers (Nginx, S3, CDN) inherently support the regular polling mode with ETag-based conditional requests.