httpdd encodes HTTP status code resolution as Cosmogol state machines you can export to JSON

The diagram resolves status codes through semantical callbacks

httpdd is an activity diagram that describes how an HTTP response status code gets resolved, given various request headers. The diagram is implemented via semantical callbacks, so each decision point is a named question about the request or the stored state, and the answer picks the next step.

The project hashtag is #httpdd, short for HTTP Decision Diagram, and the repository is one piece of a bigger effort called for-GET HTTP.

The diagram follows RFC 9110, RFC 9111 and RFC 9112, and fills in gaps where those documents are silent. For those gaps it points at RFC 6585, RFC 7725, RFC 8470, RFC 9211 and RFC 9213. The authors state that under no circumstances does the diagram override the HTTP specifications, and ask readers to file an issue as soon as possible if it ever does.

That sentence sets how to read everything else here: httpdd is a model of the specs, and when it disagrees with an RFC the RFC wins.

Cosmogol source files are the real artifact and JSON is the export

The repository root holds three diagram sources in Cosmogol: httpdd.fsm.cosmogol, httpdd-cache-retrieve.fsm.cosmogol and httpdd-cache-store.fsm.cosmogol. Each has a matching exported .fsm.json file. The diagrams are also published as PNG, JPEG and SVG, and an httpdd.fsm.png and an httpdd.fsm.html page sit in the repository.

The Makefile regenerates JSON from the sources through a build/fsm-json target, which loops over every httpdd*.fsm.cosmogol file and runs tools/cosmogol.js on it. A check/fsm-json target parses package.json and each *.fsm.json to confirm they are valid JSON.

The consequence for contributors is that editing a .fsm.json by hand is the wrong move. Change the .cosmogol file and rebuild, or the JSON and its source drift apart.

package.json points its main field at ./httpdd.fsm.json, and its version is 4.0.202610. The package is named httpdd, with keywords http, fsm, cosmogol and json.

Cache retrieval follows RFC 9111 directives one by one

The caching half of the project splits into two diagrams. Cache-retrieve decides whether to answer a request with a cached response. Cache-store decides whether to cache a response at all. Darrel Miller started something similar, in terms of deciding whether to cache or not and whether to respond with a cached response or not, and the project credits his post titled Caching is hard, draw me a picture.

Retrieval decisions follow RFC 9111. A request or storage no-cache forces revalidation. stale-while-revalidate serves stale content while revalidating. must-revalidate prevents serving stale responses.

Each directive is a branch in the diagram rather than a paragraph of prose, which is the reason to read the diagram at all: a single path from request to outcome can be followed without paging through the spec.

Targeted cache headers are read before the generic Cache-Control

The cache diagrams include Cache-Status emissions from RFC 9211 and Targeted Cache Control from RFC 9213, which covers CDN-Cache-Control. The rule is stated directly: when the cache is targeted, the Cache-Control callbacks read the targeted headers first.

That ordering matters for anyone running a CDN in front of an origin. A CDN-Cache-Control header meant for the CDN can differ from the Cache-Control meant for browsers, and the diagram resolves the targeted one before the general one.

The cache-retrieve and cache-store diagrams each have their own JSON export, httpdd-cache-retrieve.fsm.json and httpdd-cache-store.fsm.json, plus their own Cosmogol source. A tool that only needs cache logic can load those two files and ignore the main diagram.

WebDAV codes, 510 and 226 are out of scope

The diagram does not cover every status code. Out of scope are 510 Not Extended from RFC 2774, which the project labels Historic, the WebDAV codes 207, 208 and 508, and 226 IM Used from RFC 3229.

A team building a WebDAV server cannot use httpdd to decide when to emit 207 Multi-Status or 208 Already Reported. Any code path that depends on those has to be reasoned about from the RFCs directly. The same holds for delta encoding responses that would return 226.

Details of the exclusions live in doc/README.md under the diagram heading. The scope choice is worth knowing before importing httpdd.fsm.json into a validator, because a status code that the diagram never emits will appear to be an error to any test written against it.

The viewer page bundles jQuery, lodash, Backbone and JointJS

The browsable diagram is a static page. The repository root contains backbone.min.js, jquery.min.js, lodash.min.js, joint.bundle.min.js and joint.min.css next to httpdd.fsm.html, httpdd.fsm.html.coffee and a compiled httpdd.fsm.html.js. The development dependencies in package.json are backbone ^1.4.1, jointjs ^3.7.7, jquery ^3.7.1 and lodash ^4.17.21.

The page script is written in CoffeeScript, and coffee-script is pinned to ~1.8.0. The Makefile compiles httpdd.fsm.html.coffee with node_modules/.bin/coffee in a build target, and a PNG target rasterizes the page with headless Chrome and a python3 server.

Contributors therefore need Node, an npm install, and for the PNG route a headless Chrome. A reader who only wants the diagram needs none of it, since the exported formats are committed. The dist target runs npm publish for the httpdd package and requires an npm login.

No releases are tagged and the last push was 2026-10-15

The repository is not archived. Its last push was on 2026-10-15, and it is licensed Apache-2.0. The repository has no GitHub releases, so the only version marker is the 4.0.202610 string in package.json.

The repository also holds a TODO.md, a CONTRIBUTING.md, a README.more.md with further material, and two notice files named NOTICE and NOTICE2. The Makefile header describes itself as a light version of a vendored sane.mk core and says to upgrade to the full framework when the project outgrows about five leaf targets.

If you plan to depend on the JSON, pin a commit hash instead of a release, since no tag exists to point to.

Editorial conclusion

Use httpdd as a reference and a JSON state machine when you are designing or auditing how a server or cache picks a status code, and treat the RFCs as the final word since the project says it never overrides them. Do not use it for WebDAV, 510 or 226 behavior, which it excludes. Check that your JSON consumer handles the callback-based structure before building on httpdd.fsm.json.

Frequently asked questions

Official sources

1. for-GET/http-decision-diagram on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README