connection config — the SPEC config keys (L4)

In one paragraph

Creating a connection is an ordinary write — write /net/<module>/conn = SPEC{name, config} at the RFC-0014 creator endpoint, the ONE door since S7 retired the /net:children[] creation spelling — and everything the new link needs is in that config SETTINGS TLV. Its keys come in two families. The universal ones (kind, addr, port, max_frame, …) are parsed centrally into tr::net::conn_settings_t, which every transport kind shares. The kind-private ones are parsed by the selected kind’s own factory, module-side, and never land on that shared record — so quic reads tls/insecure, ws and tcp read peer_named/max_peers, can reads its bus identity and ingress bounds, and none of them can see each other’s vocabulary. This page is the key-by-key reference for both families. Two facts are worth reading before you ship: no key ever carries a file path — quic/webtransport TLS material is app-owned and a SPEC can only name one of the app’s profiles — and a SPEC-created quic/webtransport dialer verifies its peer’s certificate by default.

What this page is, and what it is not

This is the reference home for the connection-creation config keys. Before it existed, a key was discoverable only from the factory’s own Doxygen block or from core/CHANGELOG.md — including the two quic keys that decide whether a dialer authenticates its peer at all.

It is not the creation protocol: the SPEC shape, the ACL gate on the write, the /net/<module>/<name> mount and the liveness value all belong to fwd-router § the /net connection model. It is not the walk either — the positional pair grammar and its forward-compat rules are config § runtime configuration. This page is the vocabulary: which keys exist, which factory reads each one, what wire value each takes, and what it does.

Its subject is deliberately bounded to what the transport-side readers read. The creation SPEC’s own envelope (name, config) and the SUBSCRIBER QoS SETTINGS read the same positional grammar — since #985 through the same tr::wire::config_reader_t type — but they are not connection config, and the ACL SETTINGS walk keeps its own reject-unknown-keys code (#906).

The shape of a config

A config value is a SETTINGS TLV whose children are positional (NAME key, value) pairs. String-valued keys take a NAME child; integer and boolean keys take a VALUE child holding a little-endian unsigned integer. Four rules from the shared reader apply to every key on this page:

• Unknown pairs are ignored, whole — key and value — so a newer peer may send keys this node has never heard of.

• A wrong-typed value is ignored as though the key were absent; so is a VALUE payload whose size is not exactly the width this table gives (an empty payload being that rule’s trivial case). A u16 port sent as four bytes reads as absent rather than silently dropping its high bytes, and a u32 keepalive sent as two reads as absent rather than zero-extending (#928).

• A repeated key resolves to its last well-formed occurrence.

• A child that is not a NAME where a key belongs stops the walk. Every key after that point reads as absent.

The consequence that bites: there is no error return for a misspelled or mistyped key. insecrue = 1 and insecure = "1" (a NAME value where a VALUE belongs) both create a connection that silently took the default. The gate against that is reading the table below, not a status code — unless the module declares a catalog.

A module may declare its conn:schema catalog when the application registers it (register_module’s optional tr::net::conn_catalog_t, RFC-0014 §2 / Amendment 3, #1815): a static constexpr table of tr::net::conn_key_t, each naming a key, its value shape (utf8, bool, u8, u16, u32) and whether it is required. Against such a module, a SPEC that omits a required key, or carries a catalogued key in any other type or width, is refused TYPE_MISMATCH before a factory runs, and read /net/<module>/conn:schema advertises the same table. The catalog does not catch a misspelled key: a key it does not name is still an unknown pair and is ignored. With no catalog declared, the rules above are the whole story.

Writing one — tr::net::conn_spec_t

The library ships the encoder as well as the reader (libtracer/conn_spec.hpp). conn_spec_t is a fluent builder over the shape above: each setter appends one (NAME key, value) pair and returns *this, and the terminal bytes() / view() wrap the pairs in the config SETTINGS and the whole thing in the SPEC.

using tr::net::conn_role_t;
using tr::net::conn_spec_t;

// A module must exist before anything can be created in it: it mints the endpoint and
// fixes the (kind, role) pair positionally.
(void)net.register_module("ws-client", "ws", conn_role_t::DIAL);
(void)net.register_module("ws-server", "ws", conn_role_t::LISTEN);

// The one-call form — the 90% case.
graph.write(*path_t::parse("/net/ws-client/conn"),
            tr::net::conn_spec("up", 8080, "ws", "127.0.0.1"));

// The builder, for the rest: universal keys by name, kind-private keys as pairs.
// The module in the PATH fixes both the transport and the role, so the SPEC carries
// neither a `type` nor a `role`.
graph.write(*path_t::parse("/net/ws-server/conn"), conn_spec_t("srv")
                                                       .port(8080)
                                                       .max_frame(4096)
                                                       .flag("peer_named", true)   // ws-private
                                                       .u32("max_peers", 8)        // ws-private
                                                       .view());

// Removal is the other half of that one control: a bare NAME, told apart by TLV type.
graph.write(*path_t::parse("/net/ws-server/conn"), tr::net::conn_remove("srv"));

The named setters are exactly the universal keys of the next section; the generic text / u8 / u16 / u32 / flag pairs carry a kind’s private vocabulary, which the builder deliberately does not know (that coupling is what ADR-0043 §5 forbids). Their names mirror config_reader_t’s accessors, so the encode and decode vocabularies cannot drift apart.

Two properties are worth knowing before you build one:

• A builder on which no setter ran emits no config at all — that is the provide_link-staged spelling, where the module comes from the staging rather than from a kind.

• There is no module key, and the builder invents none. The endpoint a SPEC is written to is the module; a kind pair, when present, must be one that module declares. See the kind row below.

The builder does not validate a key against a kind — it cannot, for the reason above — so the misspelling hazard in the paragraph before this section is unchanged. What it removes is the other failure mode: a private near-copy of the encoder per call site, each free to drift.

Universal keys — parsed into conn_settings_t

Read once, centrally, for every kind (core/src/transport_vertex.cpp). A kind’s factory receives the parsed record alongside the raw config TLV.

key	value	applies to	default	meaning
kind	NAME utf-8	both	empty	Selects the transport factory (udp, tcp, ws, or any kind registered through register_transport_type) — and, because the endpoint’s module already fixes a (kind, role) declaration, it is a cross-check on that module, not a module selector: the module is the PATH the SPEC was written to. A kind the endpoint’s module does not declare is refused SCHEMA_NOT_FOUND rather than mounted elsewhere (ADR-0073 §4); the check runs before any staged link is consulted (#883), so a provide_link staging that merely shares the leaf NAME cannot capture the creation. Empty is legal and is the usual spelling when the module declares exactly one kind — the declared kind is then recorded on the settings so settings_of still reports what the connection is. A module declared for two or more kinds and a kind-less SPEC is refused TYPE_MISMATCH (nothing in the SPEC says which was meant). A staging under the resolved module still wins over construction; one under a different module is a different connection and is left untouched. An unregistered kind (no register_transport_type) fails only when construction is actually reached: a staging under the resolved module short-circuits ahead of the factory lookup, so a kind declared purely to disambiguate needs a register_module and no factory at all.
addr	NAME utf-8	DIAL	empty	Peer address, IPv4 dotted-quad. A DIAL with it empty answers TYPE_MISMATCH in all five socket factories — the three built-ins (udp, tcp, ws) share one precondition helper, and quic/webtransport repeat the check. can never reads it.
port	VALUE u16	both	absent	Peer port on a DIAL, bind port on a LISTEN. On a DIAL, 0 answers TYPE_MISMATCH in the same five socket factories — there is no such thing as dialling the ephemeral port. On a LISTEN the key is what is required, not a nonzero value: an absent key answers TYPE_MISMATCH (the config is missing a required field), while an explicit port = 0 is the EPHEMERAL request — the OS picks a free bind port and the grant is read back off the constructed link with local_port() (#1362). Before that the LISTEN arm rejected 0 as if it were an omitted key, which conflated “you forgot the port” with “you do not care which port” and left an in-band-created listener no way to ask for one. can never reads it.
max_frame	VALUE u32	both	0	Per-connection inbound frame cap in bytes, honoured by five of the six kinds — tcp, quic and webtransport read it off their u32 length prefix, ws off the RFC 6455 header, udp off the received datagram’s length (one datagram = one frame). 0 = the 16 MiB protocol default on the framed kinds, and udp_transport_t::kMaxDatagram (64 KiB) on udp. It only ever tightens, on every kind that reads it. On the four framed kinds each transport resolves the configured value through length_prefix_framer::configured_cap — 0 → the 16 MiB default, otherwise min(value, 16 MiB) — so a config-writable key can narrow what the node buffers off the wire but never widen it (#1035); the effective cap is then further bounded by the injected backend’s max_segment_size(). On udp it can only tighten for a different reason — a datagram cannot exceed 64 KiB, so a larger configured value is inert. A declared length over the cap is refuse-and-close on the framed kinds (malformed_rx(), then the link is torn down: a desynced stream cannot be re-framed) and refuse-and-continue on udp (malformed_rx(), socket unaffected — datagrams need no resync). A length at the cap is legal and delivered whole. On quic and webtransport the configured value bounds egress as well as ingress (#1409): a local send over the cap is shed with dropped_tx() and the link stays up, rather than being put on the wire for a conformant peer to count malformed_rx on and tear the connection down. can (its own fragmentation) does not read it.
backoff	VALUE u32	DIAL	0	Self-heal retry interval in ms (RFC-0014 §4), consumed by the S5 liveness engine (self_heal_link_t) on a kind registered self_heal_dial. 0 = the engine’s default (kDefaultBackoffMs, 1000 ms). The built-in point-to-point kinds udp, tcp and ws are opted in (#1548) on a build that carries the engine (kSelfHealLinks = true, opt-in since v0.17.0, #1670), so there this key has a consumer on every built-in DIAL. On a kind not opted in — a bus kind such as can, or any kind on a stock kSelfHealLinks = false build — it is parsed but has no consumer.
connect_timeout	VALUE u32	DIAL	0	How long one dial attempt waits for UP, in ms (RFC-0014 §4) — the S5 engine’s bound on an op’s auto-wake wait, and handed to the kind’s factory in its parsed settings. 0 = the engine’s default (kDefaultConnectTimeoutMs, 5000 ms). Same opt-in scope as backoff.

keepalive — accepted, ignored

A keepalive pair (VALUE u32, ms) is still accepted, so an existing config that spells it parses and creates exactly as before, and conn_spec_t::keepalive_ms still emits it. Nothing reads it: it is an unknown pair to the universal parse, dropped like any other (#1666). It used to be stored in conn_settings_t::keepalive_ms, a field with no consumer that every transport vertex carried; that field is gone. UDP is connectionless, TCP has its own, WS handles PING/PONG at the protocol layer — a kind that ever needs a keepalive knob parses it from its own config, like any kind-private key.

Refusals the endpoint owns, not a key

One creation refusal is not any single key’s: it is a property of the SPEC as a whole at the /net/<module>/conn endpoint, so it sits below the generated table rather than in it (tools/check_config_keys.py derives that table’s rows from the keys the source reads, and this rule is bound on an ABSENT key).

SPEC written to /net/<module>/conn	status	why
no kind, and no provide_link staging under <module>/<name>	TYPE_MISMATCH	Nothing can carry the connection’s bytes: with no kind there is no factory to construct a link, and with no staging there is no pre-built one to adopt (#1062). The config is missing a required field — the addr/port precedent — so the answer is the config-shape status, and deliberately never NOT_FOUND: RFC-0014 reserves that wire form (tr::path::not_found) for an absent creator endpoint, which is the creatability probe. The endpoint here exists and answered; it is the SPEC that is unusable. (make_connection_locked, the final arm of the link-resolution if.)

The rule outlives the spelling it was written against. Before S7 retired the /net:children[] creation door, an absent kind meant “resolve the module from the staging”, so this refusal read as “no staging matched”. At the conn endpoint the module comes from the PATH, so an absent kind is no longer a module selector at all — and the refusal binds one step later, on the link resolution, where it is still exactly as live.

Kind-private keys

Each kind’s factory parses its own keys out of the raw config TLV. Nothing here is a field on conn_settings_t, and no kind can read another kind’s key.

tcp — the LISTEN-side bus facet

key	value	applies to	default	meaning
peer_named	VALUE u8 (flag)	LISTEN	0	Non-zero exposes the bus_link_t facet (ADR-0044): each accepted peer gets its own return-route identity and the connection’s :children[] enumerates live peers. Without it a listener is a broadcast link — send fans out to every open peer and no peer is individually addressable.
max_peers	VALUE u32	LISTEN	0	Concurrent-peer admission cap (RFC-0006); a connection beyond it is accepted and immediately closed. 0 is no longer uncapped (#1295): it takes the liveness window’s own ceiling, window ÷ 100 ms — 100 on the default 10 s window — and a larger request is clamped to that ceiling. The cap is the denominator a directed send’s bound divides by, so an uncapped server had no bound at all; to admit more peers, widen liveness_window.
liveness_window	VALUE u32	DIAL + LISTEN	0	The peer liveness window (#838): how long a peer may fail to take bytes before it is treated as broken. It bounds every send (and the write-mutex hold it takes) — a broadcast record gets window ÷ peers-in-this-round and a directed record window ÷ max_peers (#1295), both floored at 100 ms — so a stalled peer can no longer freeze the sending thread, and N stalled peers cost the node one window rather than N. Three consecutive stalled records to one peer, or one that half-reached the wire, close that peer. 0 = the conservative 10 s default clamp, never “unbounded”. It also SIZES max_peers above. The number is the deployer’s, exactly as connect_timeout and CAN’s peer_ttl are; it converges into RFC-0014 §S5’s single liveness contract.

The first two are ignored on a DIAL: a client has exactly one peer, itself. liveness_window applies to both roles — a dialled client can be stalled by its server just as a listener can by a peer.

ws — the same keys, verbatim

key	value	applies to	default	meaning
peer_named	VALUE u8 (flag)	LISTEN	0	As tcp: the ADR-0044 per-peer identity facet instead of a broadcast link.
max_peers	VALUE u32	LISTEN	0	As tcp: the concurrent-peer admission cap, with 0 resolving to the liveness window’s ceiling rather than “uncapped” (#1295).
liveness_window	VALUE u32	DIAL + LISTEN	0	As tcp: the peer liveness window every send is bounded by (#838). The shipped case here is a throttled background browser tab that stops reading — it now costs counted frames and its own session, not the server’s sending thread.
max_handshake	VALUE u32	DIAL + LISTEN	0	Bytes. The pre-auth opening-handshake request budget (#934): the most an unauthenticated host — one that has completed a TCP connect and nothing else, no ACL, no subscription, no router — may make this node accumulate before its HTTP Upgrade request (LISTEN) or 101 response header block (DIAL) is refused. 0 = the 16 KiB transport_ws_server::kMaxHandshakeBytes default, and the key is tighten-only: a larger value is clamped to that default, because a config-writable key must never raise a pre-auth bound. The budget is a total-request one, not a per-read one, and it is enforced before the bytes that would exceed it are copied — over budget ticks malformed_rx and closes the link (count-then-close). It does not bound what a server pipelines behind its 101; those are frame bytes under max_frame.

udp — no kind-private keys

The udp factory constructs no config reader at all: addr/port/max_frame from the universal set, plus the role its module fixes, are the whole of its configuration. A DIAL binds an ephemeral local port and targets addr:port; a LISTEN binds port (or an OS-granted one when the key is spelled 0) and learns its peer from the first inbound datagram’s source.

This is a checked claim, not an omission — see How this page is kept true.

can — bus identity and ingress bounds

Of the six transport factories in this tree, can is the only one that ignores conn_settings_t outright — its lambda takes the record as an unnamed parameter — so addr, port, keepalive and max_frame do nothing on a can connection. (kind still matters — it is consumed by the connection vertex itself, to select this factory and to cross-check the module the SPEC was written to. A bus has no dial/listen asymmetry, so can is ONE module for both roles.)

key	value	applies to	default	meaning
ifname	NAME utf-8	both	— (required)	The SocketCAN interface (can0, vcan0). Empty answers TYPE_MISMATCH; an interface the kernel will not open answers TRANSPORT_DOWN.
node	VALUE u16	both	— (required)	This node’s id, the node band of the 29-bit CAN ID. Required — an absent key answers TYPE_MISMATCH, and so does a value above 8191 (13 bits).
version	VALUE u8	both	0	Protocol-version prefix, the top 4 bits of the CAN ID, so distinct versions occupy disjoint arbitration bands. Above 15 answers TYPE_MISMATCH.
path	NAME utf-8	both	empty	The path advertised for this node’s groups. Same spelling as the webtransport kind’s path, unrelated meaning — that one is an HTTP URL path. Kind-private keys cannot collide at parse time; the collision is in the reader’s head.
fd	VALUE u8 (flag)	both	0	Non-zero selects CAN-FD framing (≤64 B data fields) instead of classic (≤8 B).
peer_ttl_ms	VALUE u32	both	3000	Peer liveness window (ADR-0044): a peer silent longer than this leaves the enumeration.
max_groups	VALUE u32	both	0	Live reassembly-group ceiling. 0 = uncapped by this key; overflow evicts the oldest group and ticks dropped_groups.
max_pending	VALUE u32	both	0	Ceiling on data slices parked awaiting their advertise. 0 = uncapped by this key; overflow evicts the oldest and ticks dropped_rx.
rx_ttl_ms	VALUE u32	both	0	RX staleness window: a parked slice or an incomplete group untouched this long is reclaimed, so a lost advertise cannot pin one forever. 0 means track peer_ttl_ms — never “disabled”.

The two count caps and the pmr resource behind them are the ingress-bounding seam; the byte-level story is on can.

quic and webtransport — the TLS material

Two modules, one identical key set, both in the separate libtracer_quic target.

TLS material is app-owned; the SPEC never carries a file path. A creation SPEC can arrive from any writer, a remote one included, so the certificate, the private key and the CA bundle come from the application: it builds a table of named tr::net::tls_profile_t (name, ca_file, cert_file, key_file) and hands it to the factory at registration — net.register_transport_type("quic", tr::net::quic_transport_factory(profiles)). The factory keeps the span, not a copy, so the table and the strings it views must outlive the factory and every transport it builds; a constexpr table of string literals costs no RAM at all. The SPEC can at most name one of those profiles:

key	value	applies to	default	meaning
tls	NAME utf-8	DIAL + LISTEN	empty ⇒ the profile named ""	The app profile this link uses. A name the app’s table does not hold answers TYPE_MISMATCH before any file is opened. A LISTEN serves the profile’s cert_file/key_file, and with no profile — or one that leaves either empty — answers TYPE_MISMATCH; files msquic will not load answer TRANSPORT_DOWN (the listener did not come up). A DIAL verifies the peer against the profile’s ca_file, or the system trust store when there is no profile or it names no bundle.
insecure	VALUE u8 (flag)	DIAL	0	DEV ONLY, and requires the build capability config_t::kAllowInsecureTls (default false). With it, non-zero skips server-certificate validation entirely. Without it, non-zero is refused at creation with PERMISSION_DENIED on either role and counted in quic_insecure_refusals(); 0 is accepted.

webtransport reads the same two, with the same meanings, plus two keys quic has no use for — it is the only kind here with an HTTP layer, so it is the only one with a resource to name and the only one with an H3 handshake to bound:

key	value	applies to	default	meaning
tls	NAME utf-8	DIAL + LISTEN	empty ⇒ the profile named ""	The app profile this link uses; the same rules as quic.
insecure	VALUE u8 (flag)	DIAL	0	DEV ONLY, and requires config_t::kAllowInsecureTls. With it, skips server-certificate validation; without it, non-zero is refused with PERMISSION_DENIED and counted in webtransport_insecure_refusals().
max_handshake	VALUE u32	DIAL + LISTEN	0	Bytes. The pre-auth HTTP/3 handshake budget (#1408): the most a peer that has completed a QUIC handshake and nothing else — no session, no ACL, no subscription, no router — may make this node accumulate before its H3 material is refused. 0 = the 16 KiB webtransport_transport_t::kMaxHandshakeBytes default, and the key is tighten-only: a larger value is clamped to that default (webtransport_transport_t::handshake_cap), because a config-writable key must never raise a pre-auth bound. On a LISTEN it bounds per-stream classification / HEADERS accumulation and the declared length of a HEADERS or unknown/GREASE frame, so an over-declaration is refused before one body byte is buffered; on a DIAL it bounds the CONNECT response’s field section the same way. Over budget is a statement about the peer, so the connection is shut down with the bad-request code — distinct from the two exhaustion dispositions, which are stream-scoped (#919) or count-then-close (refused_sessions(), #934) and are unchanged by this key. It does not bound frame-channel bytes; those are under max_frame.
path	NAME utf-8	DIAL	/	The extended CONNECT :path — which resource the WebTransport session is opened on (new WebTransport("https://host:port/here")). Empty is normalised to /. This is an HTTP URL path, not a libtracer graph path, and it is not the can kind’s path key (an advertised group path): kind-private namespaces do not collide, but the two spellings are identical, so read the section heading before copying a row. The LISTEN side of this kind serves every path — it validates :method/:protocol only — so the key matters when dialing someone else’s server (#1023). The accepted shape is origin-form: absent, empty (⇒ /), or /-prefixed. A non-empty value that does not begin with / answers TYPE_MISMATCH at creation, before any socket or TLS work, because an https request’s :path is /-prefixed in origin-form (RFC 9114 §4.3.1 / RFC 9113 §8.3.1) — nothing beyond that leading / is judged (#1039).

tools/gen-dev-cert.sh emits a self-signed pair for a profile’s LISTEN side.

The keys ca, cert and key no longer exist. Through v0.16 they carried filesystem paths straight from the SPEC. A SPEC that still carries any of them is now refused with TYPE_MISMATCH — the same answer as an unknown profile, before any file is opened — rather than skipped like an unknown pair: skipping would move a stale dial that pinned a private CA onto the system trust store without a word. Migration: move ca/cert/key into the app’s link config — a tls_profile_t table passed to the factory — and, if more than one is needed, select it with tls.

A dial to the wrong resource is not a distinguishable failure: the server refuses the CONNECT, the session never establishes, and creation answers TRANSPORT_DOWN — the same status a certificate rejection gives. That holds for a well-formed path naming a resource the server does not serve; the one case taken out of it by #1039 is a path that is not origin-form at all, which is refused at creation with TYPE_MISMATCH rather than dialled. Before #1023 there was no key at all and the factory hard-coded /, so a SPEC could reach only a root-served session and any other server needed the direct constructor plus provide_link. On the LISTEN side, webtransport_transport_t::session_path(out) writes the :path the accepted CONNECT named into a caller buffer — an observation, never an admission decision.

Certificate trust on a SPEC-created dialer

Five points, in the order an integrator meets them.

The default is verify. A quic or webtransport dialer created from a SPEC with no profile anchor validates the peer’s certificate against the system trust store, and a certificate that does not chain to it is refused: the handshake fails and creation answers TRANSPORT_DOWN. Anything dialing a self-signed peer must say so, with a profile whose ca_file certifies it or (on a build with kAllowInsecureTls) with insecure = 1. This is a change of behaviour, not a restatement of one: before #918 the DIAL branch hard-coded no-verify and returned before the kind-private parse ran at all, so every SPEC-created dialer skipped validation and no config key existed that could change it. core/tests/quic_test.cpp and core/tests/webtransport_test.cpp drive all five legs — no key, insecure = 1, a profile whose anchor is the peer’s own cert, insecure = 0, and a profile with an unrelated bundle that is genuinely consulted and still refuses.

insecure wins when both are set. The credential is built with a single if (insecure) … else if (!ca.empty()) …, so insecure = 1 together with a profile anchor is a no-verify dial and the bundle is not consulted. That is deliberate: it matches the quic_dial_tls_t contract the direct-construction path already had, and it errs toward the mode the operator wrote down explicitly rather than toward a silently half-applied one.

Malformed insecure fails secure. Every way of getting the key wrong resolves to verify, because the reader returns “absent” and the field keeps its false default: the key omitted, the value sent as a NAME instead of a VALUE, an empty VALUE payload, and — because a VALUE is little-endian — a wide payload whose first byte is zero, which is what a big-endian 1 looks like on the wire. There is no spelling of a broken insecure that turns validation off.

insecure = 0 is not a weaker opt-out. It is the explicit spelling of the default, and it verifies.

insecure = non-zero requires a build capability. A SPEC is a wire write, and a node without an ACL policy accepts one from any connected peer, so whether the key is honoured at all is decided by the build: config_t::kAllowInsecureTls, default false. On a default build a SPEC carrying insecure = non-zero is refused at creation with PERMISSION_DENIED, on either role, and counted (tr::net::quic_insecure_refusals() / tr::net::webtransport_insecure_refusals()). It is never downgraded to a verifying dial and never honoured. ca is the way to reach a self-signed peer on such a build. A development build that needs the key binds static constexpr bool kAllowInsecureTls = true; in its config_override.hpp; the checked-in preset core/tests/insecure-tls/ does exactly that, and the quic CI workflow runs the QUIC and WebTransport tests under it as well as under the default. Only the SPEC is gated: an application that constructs a transport itself with quic_dial_tls_t{.insecure_no_verify = true} has made that choice in its own code.

Why these are not conn_settings_t fields

conn_settings_t carries only the keys every transport kind shares. That leanness is a ruling, not an accident (ADR-0043 §5): a kind’s private configuration is parsed by that kind’s own factory, inside its own module.

The reason is the module boundary. quic lives in a separate link target; a device that does not link it contains zero QUIC schema, no msquic reference and no feature macro. Putting tls/insecure on the shared record would put TLS vocabulary into the connection settings of a 16 KB MCU that will never speak TLS — and it would grow once per kind, forever, for keys no other kind can use.

So the answer to “where do I add my kind’s new key?” is: in your factory, read out of the raw config TLV it already receives, and in a block on this page. Not on conn_settings_t.

Pitfalls

• A typo is silent. No status distinguishes “key absent” from “key misspelled” from “key sent with the wrong TLV type” — all three take the default. The connection comes up looking healthy.

• can ignores the universal keys. Setting port or max_frame on a can connection changes nothing; its identity is ifname + node.

• keepalive is accepted and ignored. It is not stored anywhere (#1666); no transport in the tree reads it.

• backoff and connect_timeout are dormant. They parse, they land in conn_settings_t, and nothing reads them yet.

• max_frame cannot be used to buy headroom. It is TIGHTEN-ONLY: every framed kind resolves it through length_prefix_framer::configured_cap, which clamps a non-zero value to the 16 MiB protocol default, so max_frame = 32 MiB still tears down a 20 MiB frame as malformed (#1035). It is an ingress bound you can clamp, never loosen — a config-writable key must not be able to widen what an unauthenticated peer can make the node buffer. udp tightens too, for its own reason: a datagram cannot exceed 64 KiB, so a value above that is simply inert there. If a deployment genuinely needs larger frames, the 16 MiB ceiling is a source-level constant (length_prefix_framer::kDefaultMaxFrame), not a knob.

• peer_named is off by default, so a SPEC-created tcp/ws listener is a broadcast link and one request over it draws one reply per peer.

• peer_named may be REFUSED outright, not downgraded. A target that does not carry the ADR-0044 bus module (tr::graph::default_config_t::kBusLinks = false, the default since v0.17.0 — see transport.md §”Closing the bus module out at build time”) carries no peer-named tier at all, so both stream factories answer peer_named = 1 with TYPE_MISMATCH and create no connection. The status is deliberately the permanent one rather than the transient TRANSPORT_DOWN a failed bind gets: no retry will make that build grow a bus facet. Serving the key as if it had said 0 would be worse than either, because the listener’s own per-frame tier select reads its constructed mode — a listener demoted only at the router would keep delivering peer-named into a sink nothing installed.

• The builder types the universal keys, not the kind-private ones. conn_spec_t’s named setters (#902) make kind, addr, port and the four u32s unmisspellable, and they replaced the sixteen hand-written emitters that used to exist. (The role setter is gone with the key: S7 made the role positional — it is the module in the endpoint’s path.) A kind’s PRIVATE keys still go through the generic text/u8/u16/u32/flag pairs — the builder cannot know them without the coupling ADR-0043 §5 forbids — so for those, a key’s spelling is still only as good as the string literal next to it.

How this page is kept true

Every key table above sits inside a marker block naming the source file that reads it, and tools/check_config_keys.py derives the same information from that file — it finds each config_reader_t construction and reads the accessor calls on it, so the key and its wire value type come from the code, not from a maintainer’s memory. The gate fails on three things: a key the source reads and the page omits, a key the page lists and the source no longer reads, and a source file that reads connection config with no block on this page at all. The last one is what keeps the sweep honest — a new kind cannot be added with its keys documented nowhere, and udp’s “no kind-private keys” is a derived fact rather than a claim.

The scope of that gate is connection config, and the scope is deliberate: the creation-SPEC envelope and the SUBSCRIBER QoS parse in core/src/graph_fields.cpp read their grammar through the same shared config_reader_t since #985, so that file is explicitly excluded from the sweep — its keys are not connection config — and the ACL walk constructs no reader at all.

tools/check_config_keys.py            # the gate
tools/check_config_keys.py --list     # the derived inventory, one key per line