nexusheaders

package
v0.32.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package nexusheaders is the single definition of the X-Nexus-* request header convention: the one way a client of a web-facing Nexus IO transport passes per-request out-of-band context — tenant, locale, timezone, an upstream authorization subject, a trace correlator — to the plugins running inside the engine.

Why a convention and not a config key per header

The alternative is every transport growing its own allowlist of header names, and every deployment editing four YAML blocks to add one field. A reserved prefix costs nothing to extend: a caller that wants to pass `X-Nexus-Timezone` just sends it, and every transport already carries it. The prefix is what keeps that open-endedness safe — it is a namespace no standard or proxy-injected header occupies, so "forward everything in it" cannot accidentally forward an Authorization, a Cookie or an X-Forwarded-For.

These values are client-controlled

Extract normalizes and bounds them; it does NOT authenticate them. A header says only what the caller typed. Identity verification is pkg/nexusauth's job, and a header is never a substitute for it: `X-Nexus-Tenant: acme` is a hint about which tenant the caller CLAIMS, useful once the credential the request also carried has been validated, and worthless on its own. For the same reason the engine binds them into the reserved (host-only, prompt- invisible) session-label namespace rather than the general one — see engine.SessionWorkspace.SetRequestHeaders — so reaching an LLM prompt is a deliberate opt-in (nexus.system.dynvars' request_headers allowlist) rather than the default.

Index

Constants

View Source
const (
	// MaxCount is the greatest number of X-Nexus-* headers carried from one
	// request.
	MaxCount = 32
	// MaxNameBytes bounds one normalized name.
	MaxNameBytes = 128
	// MaxValueBytes bounds one value.
	MaxValueBytes = 4096
	// MaxTotalBytes bounds the sum of all names and values kept.
	MaxTotalBytes = 16384
)

Bounds on what Extract will carry out of one request. They exist because every extracted header is persisted into session metadata and may be rendered into a prompt: an unbounded map would let a caller inflate the session file and the context window at will.

Exceeding a bound drops entries rather than failing the request. A header is supplementary context by construction — refusing an otherwise valid turn because the caller sent a 33rd one would trade a real request for a cosmetic rule. Dropping is deterministic (see Extract) so the same request always yields the same map.

View Source
const Prefix = "X-Nexus-"

Prefix is the header-name prefix that marks a request header as Nexus out-of-band context. Matching is case-insensitive, as HTTP field names are.

Variables

This section is empty.

Functions

func Extract

func Extract(h http.Header) map[string]string

Extract returns every X-Nexus-* header of h keyed by its normalized name, or nil when the request carries none. The result is safe to retain: it shares nothing with h.

Repeated field lines are joined with ", ", the combination RFC 9110 §5.3 already defines for a list-valued field, so a caller that sends one header twice and a caller that sends one comma-joined header are indistinguishable to a plugin — which is what the RFC promises them.

Over-bound input is dropped in a defined order: names are sorted, then kept while MaxCount and MaxTotalBytes allow. Sorting first is what makes the dropping deterministic — the same request yields the same map on every run and in a replay, instead of whichever entries Go's map iteration happened to reach first.

func Name

func Name(field string) (string, bool)

Name normalizes one HTTP field name to the key plugins see, reporting whether the field belongs to the X-Nexus-* namespace at all.

`X-Nexus-Tenant-ID` becomes `tenant-id`: the prefix is stripped and the remainder lowercased, so a caller's capitalization never changes the key a plugin reads. A bare `X-Nexus-` with nothing after it is not a name and is rejected, as is any remainder carrying a character outside the set a session-label key and a prompt line can both hold verbatim.

func Sanitize

func Sanitize(in map[string]string) map[string]string

Sanitize applies the same normalization and bounds to a map that already claims to hold X-Nexus-* values, and is the entry point for values that did NOT arrive on an http.Header — a transport that carries them in its own payload, such as the per-turn headers a client may attach to the session broker's instance IO envelope.

Names may be written either normalized (`tenant-id`) or with the prefix still on (`X-Nexus-Tenant-ID`); both land on the same key. A name that could not have come off a real header — wrong character set, empty, over-long — is dropped rather than corrected, because a caller that sent one has a bug and silently reshaping it would hide that.

Sharing the bounds with Extract is the point of the function existing. These values reach the same places (session metadata, potentially a prompt), so a second entry point with its own limits would be a second, weaker door into the same room.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL