{"id":49918372,"url":"https://github.com/groupsum/cache-freshness-governance-pack","last_synced_at":"2026-05-16T18:01:05.224Z","repository":{"id":356434878,"uuid":"1232520204","full_name":"groupsum/cache-freshness-governance-pack","owner":"groupsum","description":"Installable SSOT ADR/SPEC extension pack for HTTP caching, freshness, validators, stale controls, Cache-Control, ETag, and CDN cache governance.","archived":false,"fork":false,"pushed_at":"2026-05-08T05:33:47.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-08T05:37:47.553Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/groupsum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T02:33:03.000Z","updated_at":"2026-05-08T05:33:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/groupsum/cache-freshness-governance-pack","commit_stats":null,"previous_names":["groupsum/cache-freshness-governance-pack"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/groupsum/cache-freshness-governance-pack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupsum%2Fcache-freshness-governance-pack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupsum%2Fcache-freshness-governance-pack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupsum%2Fcache-freshness-governance-pack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupsum%2Fcache-freshness-governance-pack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/groupsum","download_url":"https://codeload.github.com/groupsum/cache-freshness-governance-pack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupsum%2Fcache-freshness-governance-pack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33113509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-16T18:01:03.347Z","updated_at":"2026-05-16T18:01:05.218Z","avatar_url":"https://github.com/groupsum.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003ecache-freshness-governance-pack\u003c/h1\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://pypi.org/project/cache-freshness-governance-pack/\"\u003e\u003cimg alt=\"PyPI version\" src=\"https://img.shields.io/pypi/v/cache-freshness-governance-pack.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pepy.tech/projects/cache-freshness-governance-pack\"\u003e\u003cimg alt=\"Downloads\" src=\"https://static.pepy.tech/badge/cache-freshness-governance-pack\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hits.sh/github.com/groupsum/cache-freshness-governance-pack/\"\u003e\u003cimg alt=\"Hits\" src=\"https://hits.sh/github.com/groupsum/cache-freshness-governance-pack.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/cache-freshness-governance-pack/\"\u003e\u003cimg alt=\"Python versions\" src=\"https://img.shields.io/pypi/pyversions/cache-freshness-governance-pack.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/groupsum/cache-freshness-governance-pack/blob/master/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/pypi/l/cache-freshness-governance-pack.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/groupsum/cache-freshness-governance-pack/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/groupsum/cache-freshness-governance-pack/actions/workflows/ci.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/groupsum/cache-freshness-governance-pack\"\u003e\u003cimg alt=\"GitHub repo\" src=\"https://img.shields.io/badge/GitHub-groupsum%2Fcache--freshness--governance--pack-181717?logo=github\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n`cache-freshness-governance-pack` is an SSOT Registry pack for HTTP caching, freshness, validators, cache directives, stale response behavior, targeted cache policy, and CDN-facing cache governance.\n\nIt gives product, platform, reliability, and edge-delivery teams a shared set of Architecture Decision Records (ADRs) and Specifications (SPECs) for cache behavior. Centralizing these requirements lets teams apply the same freshness and caching decisions across many services, APIs, sites, and CDNs while keeping local implementation work traceable to reviewed standards.\n\n## What Is An SSOT Registry Pack?\n\nAn SSOT Registry pack is an installable package of governed ADRs and SPECs for [`ssot-registry`](https://pypi.org/project/ssot-registry/). The pack supplies reusable decision and requirement documents. `ssot-registry` applies those documents to a project registry so teams can trace product requirements from decision, to specification, to implementation, to tests and release evidence.\n\nThis makes governance portable. A project can adopt the pack, synchronize the documents, list the active requirements, and connect local features or tests to the shared IDs.\n\n## Why This Pack Exists\n\nCaching looks simple until products need predictable freshness, validator behavior, stale response policy, CDN-specific directives, cache observability, and consistent release review. The same `Cache-Control` or `ETag` mistake can create stale pages, overloaded origins, broken rollback paths, misleading CDN behavior, and confusing customer experiences.\n\nThis pack helps teams:\n\n- apply reviewed HTTP caching and freshness requirements across projects\n- align origin, shared cache, browser, and CDN behavior around the same governed IDs\n- turn RFC and IETF review into reusable ADRs and SPECs\n- connect cache policy decisions to implementation, tests, and release evidence\n- make edge-delivery reviews more consistent for APIs, web apps, static assets, and content platforms\n\n## Domain Focus\n\nThe pack focuses on product and platform domains where cache behavior affects correctness, performance, reliability, and user trust:\n\n- HTTP cache policy for sites, APIs, and service responses\n- freshness calculation, max-age policy, and expiry behavior\n- validators such as `ETag`, `Last-Modified`, and conditional requests\n- `Cache-Control`, `Expires`, `Age`, and `Vary` governance\n- stale response controls such as `stale-while-revalidate` and `stale-if-error`\n- immutable/versioned asset response policy\n- targeted cache control and `CDN-Cache-Control`\n- cache diagnostics through `Cache-Status`\n- cache grouping and invalidation requirements\n- structured field syntax for cache extensions\n- IETF, RFC, and IANA registry target review for cache/freshness surfaces\n\n## Included ADRs\n\n- `adr:0900` cache/freshness standards targets are reviewed before governance inclusion\n\n## Included SPECs\n\n- `spc:0900` cache/freshness governance target review\n\n## Standards Review Targets\n\nThe first release includes a standards target inventory for cache/freshness review. It covers current core candidates, supporting candidates, historical/superseded context, and non-IETF watchlist items. Review the inventory on GitHub:\n\n[Cache/Freshness RFC and IETF Target Inventory](https://github.com/groupsum/cache-freshness-governance-pack/blob/master/docs/standards/cache-freshness-rfc-ietf-targets.md)\n\nThe current review set includes RFC 9111, RFC 9110, RFC 5861, RFC 8246, RFC 9213, RFC 9211, RFC 9875, RFC 9651, and related IANA cache registries.\n\n## Install With uv\n\nInstall the pack into a project environment:\n\n```bash\nuv add cache-freshness-governance-pack\n```\n\nInstall it alongside the SSOT Registry CLI:\n\n```bash\nuv add ssot-registry cache-freshness-governance-pack\n```\n\nRun without adding dependencies to a project:\n\n```bash\nuvx --from ssot-registry --with cache-freshness-governance-pack ssot --help\n```\n\n## Install With The SSOT Registry Pack CLI\n\nPack-enabled SSOT Registry environments can install and synchronize packs through the pack command surface:\n\n```bash\nuvx --from ssot-registry ssot pack install cache-freshness-governance-pack\nuvx --from ssot-registry ssot pack sync . cache-freshness-governance-pack\n```\n\n## Use With The SSOT Registry CLI\n\nAfter the pack is installed in the same environment as `ssot-registry`, synchronize ADRs and SPECs into a target repository:\n\n```bash\nuv run ssot adr sync .\nuv run ssot spec sync .\n```\n\nReview the synchronized governance surface:\n\n```bash\nuv run ssot adr list .\nuv run ssot spec list .\nuv run ssot spec get . --id spc:0900\n```\n\nUse the IDs from this pack when linking project features, tests, claims, and release evidence in your local `.ssot` registry.\n\n## Programmatic Usage\n\n```python\nfrom cache_freshness_governance_pack import load_document_manifest, read_packaged_document_text\n\nadr_manifest = load_document_manifest(\"adr\")\nspec_manifest = load_document_manifest(\"spec\")\n\nprint(adr_manifest[0][\"id\"])\nprint(spec_manifest[0][\"id\"])\n\ntext = read_packaged_document_text(\"spec\", \"SPEC-0900-cache-freshness-governance-target-review.yaml\")\nprint(text[:120])\n```\n\n## Resources\n\n- GitHub repository: [groupsum/cache-freshness-governance-pack](https://github.com/groupsum/cache-freshness-governance-pack)\n- PyPI package: [cache-freshness-governance-pack](https://pypi.org/project/cache-freshness-governance-pack/)\n- SSOT Registry: [ssot-registry](https://pypi.org/project/ssot-registry/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupsum%2Fcache-freshness-governance-pack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupsum%2Fcache-freshness-governance-pack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupsum%2Fcache-freshness-governance-pack/lists"}