httpingress

Think of Microbus as a closed garden that requires a special key to access. In order to send and receive messages on Microbus, it’s necessary to communicate over NATS using a specific protocol. This is basically what the Connector facilitates for service-to-service calls.

Practically all solutions require interaction with a source that is outside Microbus. The most common scenario is perhaps a request generated from a web browser to a public API endpoint. In this case, something needs to bridge the gap between the incoming real HTTP request and the HTTP messages that travel over Microbus. This is where the HTTP ingress proxy comes into play.

On one end, the HTTP ingress proxy listens on port :8080 for real HTTP requests; on the other end it is connected to NATS. The ingress proxy converts real requests into requests on the bus; and on the flip side, converts responses from the bus to real responses. Because the bus messages in Microbus are formatted themselves as HTTP messages, this conversion is trivial, with minor adjustments:

  • The proxy filters out Microbus- control headers from coming in or leaking out
  • The first segment of the path of the real HTTP request is treated as the hostname of the microservice on the bus. So for example, POST request http://localhost:8080/echo.example/echo is translated to a bus POST request https://echo.example/echo which is then mapped to the NATS subject microbus.443.example.echo.|.POST.echo.
  • Port :443 is assumed by default when a port is not explicitly specified. Internal ports can be designated in the first segment of the path. For example, http://localhost:8080/echo.example:1234/echo is mapped to the bus address https://echo.example:1234/echo.
  • The empty root path is transformed to /root, therefore http://localhost:8080/ is mapped to https://root.

Internal ports below :1024 are reserved for endpoints that should not be reachable from outside the bus, such as outbound events on :417, task endpoints on :428, the :888 control plane, and other internal-only endpoints on :444. Outside LOCAL deployment the ingress forwards only to :443 plus the ports listed in the operator’s AllowedInternalPorts allowlist; a request for any other internal port returns 404.

Configuration

The HTTP ingress proxy supports several configuration properties that can be set in in config.yaml:

http.ingress.core:
  Ports: 80, 443 tls, 8080
  AllowedInternalPorts: 1234, 10000-11000

Ports is a comma-separated list of real HTTP ports on which to listen for requests. The default is to listen on port :8080. A port may carry an optional tls marker (e.g. "443 tls") to terminate TLS using the cert store described in the TLS Termination section below. A bare port enables TLS when its {port}-cert.pem and {port}-key.pem files are present in the working directory, so single-cert-on-:443 deployments need no marker. Port :80 is always plaintext; an explicit "80 tls" is rejected at startup.

AllowedInternalPorts is the operator-tunable allowlist of internal destination ports the ingress is willing to forward to, in addition to the implicitly-allowed :443. Entries are comma-separated and may be a single port or an inclusive range N-M, for example "1234, 10000-11000". All entries must satisfy 1024 <= port <= 65535; the microservice refuses to start otherwise. This restriction also keeps the trust-root tier (:666) and control plane (:888) out of reach — they cannot be allowlisted in any deployment mode. In LOCAL deployment the allowlist is ignored entirely and every internal port above :1023 is reachable for dev ergonomics.

TLS Termination

On a tls-marked port the ingress terminates TLS using the reusable httpx.CertStore, which indexes certificates by their leaf SAN DNS names and selects one per handshake via SNI. The file-name convention in the working directory is {port}-cert.pem / {port}-key.pem for a per-port default, or a bare cert.pem / key.pem pair as the server-wide default. Multiple cert/key pairs may live in the directory; each is indexed by the SAN names on its leaf certificate, so wildcard and multi-SAN certs work without any special handling.

Per-handshake resolution is exact SAN, then wildcard SAN, then the listener’s per-port default, then the server-wide default. With no match the handshake fails closed rather than serving an arbitrary default certificate.

The cert store watches the working directory and reloads automatically when files change, so the standard rotation patterns — atomic-rename, symlink-swap, Kubernetes secret remounts, certbot renewals — take effect without a restart.

Four config properties are used to safeguard against long requests:

  • ReadHeaderTimeout is the timeout to read the request’s header
  • ReadTimeout is the timeout to read the full request, including the header
  • TimeBudget is the time budget allocated to the downstream microservice to process the request
  • WriteTimeout is the timeout to write the response back to the client

RequestMemoryLimit is the memory capacity used to hold pending requests, in megabytes.

AllowedOrigins is a comma-separated list of CORS origins to allow requests from. The * origin can be used to allow CORS request from all origins.

Respected Headers

The HTTP ingress proxy respects the following incoming headers:

  • Accept-Encoding with br, deflate or gzip can be used to compress the response
  • X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto and X-Forwarded-Prefix are augmented with the ingress proxy’s information
  • Origin may cause a request to be blocked

Middleware

The HTTP ingress proxy employs the middleware pattern in which requests are channeled through a chain (or pipeline) of sub-processors that each performs only a part of the overall processing of the request. The HTTP ingress proxy comes preset with a reasonable default middleware chain. Applications have full flexibility to customize, replace and remove any of the preset middleware, or create and insert custom middleware.

Backward httpegress httpingress/middleware Forward