Kubo 0.40.0: CID Profiles, Codec Controls, Delegated Routing

The gateway got explicit about content negotiation

Two of the IPIPs in 0.40.0 are about the gateway deciding what to send and in what format. IPIP-523 makes the `?format=` query parameter take precedence over the `Accept` header when a client asks for a particular representation. IPIP-524 disables codec conversion by default. Together they push the gateway toward an explicit, predictable content-negotiation model: what you ask for by format is what you get, and the gateway will not silently re-encode content into a codec you did not request.

The practical consequence is that clients and gateways have to agree on formats more deliberately. If you have a client that previously relied on the gateway to convert content into a convenient format, that reliance may break on 0.40.0, because the conversion is now off by default. Audit your client's Accept handling before you upgrade a gateway that serves it.

CID profiles and the shape of a fetch

IPIP-499, UnixFS CID profiles, is the more architectural addition. It defines a way to parameterize the traversal of UnixFS DAGs through the CID itself, so a request can carry information about how the content should be walked. This is groundwork for more varied content structures, and it is the kind of change that is easy to understate: it does not change a simple fetch today, but it sets the stage for fetches that are more explicit about the shape of the data they want.

For most operators, 0.40.0 is the version where this profile mechanism first appears. You do not have to act on it, but you should be aware that the CID space is carrying more meaning than it did before, and that future tooling may use it.

Delegated routing: a new role for a full node

0.40.0 adds the ability for light clients to use a full node for delegated routing. A light client does not run the full DHT; it asks a reachable full node to do routing lookups for it. If your node is stable and publicly reachable, 0.40.0 means it can now be asked to serve that role.

That is a workload you should choose, not inherit. Delegated routing adds DHT lookup load to your node, and the requests come from other people's light clients. If you run a node that you want to keep lean, or that sits behind a NAT where you are not a stable anchor, you want to understand the delegation settings before enabling or discovering that you are serving it.

New diagnostics worth using

0.40.0 adds `ipfs diag datastore` and `ipfs swarm addrs autonat`. The first is a way to inspect the state and health of the datastore, which is where a node's content physically lives. The second reports the addresses a node believes it is reachable at, including the autonat assessment, which is the mechanism that tells a node whether its inbound addresses are actually reachable from outside.

These are the two commands to reach for when a node is behaving badly: the datastore command when content operations are failing, and the autonat command when the node is not being found by others. Both turn a class of vague 'my node is flaky' problems into concrete, inspectable state.

What to verify on upgrade

Because 0.40.0 changes default gateway behavior (codec conversion off, format precedence), the upgrade checklist is: confirm your clients still receive the content they expect, check that any content you serve in a non-default codec is reachable with an explicit `?format=`, and run the new diag commands to establish a baseline for datastore and reachability. If you serve a public gateway, the content-negotiation changes are the part most likely to surface a client incompatibility, so test representative traffic before a broad roll-out.

Sequencing the upgrade safely

The right order for a 0.40.0 upgrade is to test the gateway first, because that is where the default behavior changes. Stand up a node on 0.40.0 against a snapshot of your datastore, point a representative client at it, and confirm the content it fetches matches what it fetched before the upgrade. If a client relied on the gateway re-encoding content into a convenient format, that is the specific failure to look for, because codec conversion is now off by default and the client has to request the format it wants explicitly.

Once the gateway path is confirmed, the rest of the verification is the new diagnostics and the provider role. Run the datastore and autonat commands to establish a baseline, and if your node is publicly reachable, decide deliberately whether you want it to serve delegated routing for light clients or keep that role off. That decision is a configuration choice, not a default, and it is the one most likely to be made by accident rather than by intent if you simply upgrade and let the new capability sit there. A careful 0.40.0 upgrade is one where each of the new defaults is a choice you made, not a state you inherited.

Limitations

• A release note is not a deployment audit. It does not inspect your operating system, network policy, credentials, storage, backups, or administrative process.
• Version numbers and documentation change. Pin the exact artifacts you test, record the date, and re-check upstream material before a production change.
• A feature that exists in a package or command does not automatically fit your threat model. Authentication, authorization, logging, patching, recovery, and abuse controls remain operator responsibilities.
• This article contains no benchmark, uptime promise, adoption statistic, cost saving, or client result. Measure those claims in your environment; the release record can only describe what shipped.

Related infrastructure context

For the physical layer around a systems deployment, TismTek provides fiber and network infrastructure work near Aurora. The team also documents on-premises compute and private AI systems. For a site discussion, call (720) 694-1976. See the IPFS/Kubo content addressing and provider records for recovery planning and the private AI systems overview for the broader on-premises context.