Home /Modules/http-2.0/README.md

README.md

http-2.0/README.md · 232 line(s) · markdown

<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">

<img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela/sleela-logo-004.jpg" alt="SLeeLa">

SLeeLa HTTP 2.0 / 2.1

Status: SLeeLa HTTP 2.0/2.1 application-protocol implementation and reference server. Public internet deployment requires a protected transport, authentication, authorization, and a hardened front proxy.

Platforms: Linux · macOS · Windows 10+

HTTP 2.0/2.1 extends the SLeeLa HTTP 1.0 model with compact application envelopes, fast service/operation naming, request correlation, retry classification, and a traceable processing pipeline. It shares the basic design goals of HTTP 3.0 but is the earlier generation — it carries the clean core only, without the 3.0-era per-packet integrity substrate (no keyed-MAC DIGEST, INTACTX, NONCE, or BASKET).

Build and test

make            # build the h21_server binary, protocol objects, negotiation objects
make test       # run the built-in self-test suite
make test-python # run strict Python protocol regression tests
make syntax     # syntax-only check of all sources
make proto      # build protocol-core objects only
make clean      # remove build artefacts

Platform notes

PlatformSocket layerCompilerLink flags
LinuxPOSIX sockets via sleela_netcc / gcc(none)
macOSPOSIX sockets via sleela_netcc / clang(none)
Windows 10+Winsock2 via sleela_netMSVC / MinGW-lws2_32

The Makefile detects Windows via $(OS) and adds -lws2_32 automatically.

Running the server

./h21_server --port 8081

Options:

The server logs to stderr and runs until interrupted (SIGINT / SIGTERM on POSIX; Ctrl-C on Windows).

Architecture

TCP endpoint (HTTP/1.0 or HTTP/1.1; no TLS in this server)
        |
HTTP/1.x request / connection       ← sleela_net portable sockets
        |
SLeeLa envelope / route             ← X-SLeeLa-* untrusted hints
        |                               or H2.1 compact envelope in body
SLeeLa logical PORT
        |
SERVICE-ID / OP-ID
        |
REQUEST-ID
        |
Pipeline dispatch → handler → response

Logical ports are application identifiers and are independent of native TCP/UDP socket numbering.

Core capabilities

CapabilityStatusNotes
Compact application envelopeImplementedTextual + binary wire forms
Fast service/operation namingImplementedConnection-local name→id dictionary
Response modelImplementedTransport ≠ application status
Retry classificationImplementedREAD / IDEMPOTENT / MUTATING
Processing pipelineImplementedRegister, dispatch, wire handling
Request correlationImplementedREQUEST-ID echo
HTTP/2 transport/multiplexingNot implementedCurrent native server uses HTTP/1.x
Per-packet integrity gateNot in 2.1Added by HTTP 3.0

Wire forms

Envelope (textual):  H21 <ver> <flags> <service_id> <op_id> <request_id> <len>:<payload>\n
Response (textual):  H21R <status> <request_id> <len>:<result>\n
Envelope (binary) :  [ver:1][flags:1][service_id:4][op_id:4][request_id:8][payload_len:4][payload:N]

The binary header is 22 bytes. The textual and binary forms are auto-detected on the wire by checking the leading bytes for the H21 ASCII tag.

Built-in endpoints

PathMethodDescription
/__sleela/healthGETReturns SLeeLa HTTP/2.1 OK
/__sleela/statusGETJSON: server, generation, VM, platform, pipeline status
/__sleela/negotiateGETVersion negotiation result (JSON)
/__sleela/h21POSTH2.1 envelope endpoint — accepts textual or binary envelope, dispatches through the pipeline, returns textual response

SLeeLa application headers

Every response includes version advertisement:

X-SLeeLa-Version: 2.1
X-SLeeLa-Accept: 2.1, 2.0, 1.1, 1.0

These are untrusted routing hints, not authentication or authorization. The server must authorize every operation. Clients may set the following request headers for SLeeLa logical routing:

HeaderPurpose
X-SLeeLa-VersionRequested SLeeLa protocol generation
X-SLeeLa-AcceptComma-separated acceptable generations
X-SLeeLa-PortLogical port (application route)
X-SLeeLa-Service-IDService identifier
X-SLeeLa-Op-IDOperation identifier

Envelope endpoint usage

POST a textual or binary H2.1 envelope to /__sleela/h21:

# Register service "echo" op "echo" (done by default in the demo server)
# Send a textual envelope: service_id=1, op_id=1, request_id=42, payload="ping"
curl -X POST -d 'H21 2 0 1 1 42 4:ping' http://localhost:8081/__sleela/h21
# Response: H21R 0 42 4:ping

Port and stream multiplexing (design model, not current transport)

The current native server uses HTTP/1.x and does not implement IETF HTTP/2 framing, HPACK, HTTP/2 streams, or TLS. The following describes the intended future transport model, not a current capability. HTTP 2.1 defines three independent addressing layers:

LayerPurpose
Native transport endpointPhysical/network connection endpoint
HTTP/2 streamMultiplexed request/response channel
SLeeLa logical portApplication service/channel/route identifier

Multiple logical ports can share the same HTTP/2 connection and its stream pool. Stream identifiers and SLeeLa logical ports are different namespaces and must not be conflated.

Large-file download mode

Files larger than 50 MB use SLeeLa DOWNLOAD mode with resume metadata:

SESSION-ID | DATETIME | FILE-ID | FILE-NAME | INDEX | OFFSET | TOTAL-SIZE

A resumed request selects FILE-ID and its transfer INDEX/OFFSET rather than depending on the original connection remaining open.

What HTTP 2.1 deliberately omits (3.0-era additions)

FeaturePresent?
Keyed-MAC DIGEST (SipHash-2-4)❌
INTACTX host identity / tamper RESET❌
Replay NONCE❌
Goods & services BASKET❌
Per-packet integrity gate in the pipeline❌

Negotiation

Generation selection is explicit. A peer must accept the proposed generation before it is selected. Where fallback is permitted, the negotiation layer may return to HTTP/1.1 and then HTTP/1.0. Fallback must not silently remove a security property. See HTTP.NEGOTIATION.md.

File inventory

FileDescription
h21_server.hServer API, HTTP request/response types, download state
h21_server.cFull server: parse, route, envelope endpoint, self-test
h21_main.cCLI entry point with demo echo service
h21_protocol.hAggregation header (envelope + naming + pipeline)
h21_envelope.hEnvelope + response types, pack/unpack signatures
h21_envelope.cEnvelope init, textual/binary pack/unpack, response
h21_naming.hFast-naming dictionary types
h21_naming.cName→id interning, lookup, reverse lookup
h21_pipeline.hPipeline types, retry classes, handler binding
h21_pipeline.cService/op registration, dispatch, wire handling
h21_flow.pyPython parity implementation (envelope/response)
http_negotiation.hC negotiation API
http_negotiation.cVersion negotiation with policy checks
http_negotiation.hppC++ negotiation wrapper
http_negotiation.cppC++ wrapper implementation
MakefileBuild: all, server, proto, syntax, test, clean
FLOW.mdData-flow diagram and wire-form specification
HTTP.NEGOTIATION.mdNegotiation protocol for SLeeLa HTTP 1–9
STATUS.mdDesign-goal parity table and implementation status

Security and deployment

Read HTTP21.SECURITY.md before exposing the server. In particular, H21 2.1 has no packet integrity or replay protection; X-SLeeLa-* headers are not identity; and the synchronous server is not intended to be an internet-facing edge server by itself.

Dependencies

ModulePathRole
sleela_netimpl/core/sleela_net.{c,h}Portable TCP sockets
preferred_routerpreferred-routers/Routing-tier policy
resolverresolver/DNS / path / event policy

Unified route data

This server consumes the SLeeLa unified route-data contract in route/ROUTE.DATA.json and route/ROUTE.DATA.md. Route records carry protocol, server surface, HTTP generation, VM generation/formal VM name, canonical configuration root, route identifier, target/resolution mode, capability, transport, port, and status. VM names are architectural metadata only and do not grant capabilities. Dynamic targets must use the shared resolver before acceptance. The VM identity is: /impl Core, /1 Foundation, /2 Operator, /3 Specialist, /4 Supervisor, /5 Manager, /6 Director, /7 Administrator, /8 Executive, /9 Authority, /10 Principal, /11 Sovereign.


SLeeLa

<p align="center"><img src="images/sleela/sleela-wordmark.svg" alt="SLeeLa — The Now. The Ingredient." width="560"></p> <p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela-programming-language-002.jpg" alt="SLeeLa Marketing Logo" width="560"></p>