Prepare repo for open source

Author: huntharo

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GIPHY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,8 @@
 # GIPHY Bandwidth Saver
 
-GIPHY Bandwidth Saver is a local demo proxy that validates GIPHY media with the origin while avoiding redundant media downloads when the same GIF rendition has already been observed. It is intentionally not a login proxy, not a crawler, and not an offline mirror. The design keeps GIPHY in the request path for freshness and removal semantics while reducing repeated transfer of identical media bytes.
+GIPHY Bandwidth Saver is an MIT-licensed reference implementation for a revalidating GIPHY media cache. It includes a local website/API proxy so you can demo the behavior against the live GIPHY website, plus conformance harnesses that other implementations can adapt to prove request accounting, revalidation, replacement, deletion, and range behavior.
+
+This repository is intentionally not a drop-in production proxy, not a login proxy, not a crawler, and not an offline mirror. The reusable idea is narrower: keep GIPHY in the request path for freshness and removal semantics while avoiding redundant media-byte downloads when the same GIF rendition has already been observed.
 
 <img width="1440" height="1058" alt="image" src="https://github.com/user-attachments/assets/49cf8b22-2c93-45fe-a6cf-7a5b4a4e34ef" />
 
@@ -20,7 +22,7 @@ This project demonstrates a corporate-friendly middle ground:
 
 The result complies with the spirit of origin-controlled media delivery: GIPHY continues to receive validation traffic with enough request context to inform popularity-driven ranking and removal decisions, while consumers avoid unnecessary bandwidth spend and preserve user anonymity.
 
-## Runtime
+## Demo Quick Start
 
 This project uses pnpm and Node 24.
 
@@ -37,7 +39,9 @@ Then open:
 https://web.localhost:8080
 ```
 
-The server listens on `127.0.0.1` and uses local HTTPS with HTTP/2 by default. That default matters: without HTTP/2, the browser-to-proxy side no longer behaves like the CDN path and media loading looks much slower than the cache design actually is. You can override runtime paths with:
+This starts the local website proxy for `giphy.com`, rewrites page/API/media URLs to local hostnames, and routes media requests through the revalidating media cache. Scroll the proxied GIPHY homepage to load GIFs, then scroll back through already-seen media while watching the TUI. Repeated media should still be revalidated upstream, but upstream `304` responses should let the proxy serve local bytes and count avoided downloads.
+
+The server listens on `127.0.0.1` and uses local HTTPS with HTTP/2 by default. That default matters for the demo: without HTTP/2, the browser-to-proxy side no longer behaves like the CDN path and media loading looks much slower than the cache design actually is. You can override runtime paths with:
 
 ```sh
 PORT=8081 CACHE_DIR=cache pnpm dev
@@ -118,7 +122,7 @@ The web and API proxies rewrite GIPHY host strings based on response content typ
 
 ## Code Boundaries
 
-The demo-only website/API rewriting code is intentionally isolated from the media cache. This keeps the reusable bandwidth-saving path obvious.
+The demo-only website/API rewriting code is intentionally isolated from the media cache. This keeps the reusable bandwidth-saving reference path obvious.
 
 Demo proxy files:
 
@@ -139,6 +143,8 @@ Shared infrastructure:
 
 Architecture tests assert that media cache modules do not import demo rewrite helpers and demo rewrite modules do not import cache storage.
 
+For another implementation, the media-cache contract is the part to study first. The website/API proxy is scaffolding for making the reference implementation easy to run in a browser.
+
 ## Upstream Networking
 
 All upstream GIPHY calls use an explicit HTTPS keep-alive agent instead of relying on Node's global defaults. The agent keeps HTTP/1.1 connections reusable across requests, caps socket fan-out, and keeps a bounded pool of idle sockets:
@@ -276,7 +282,7 @@ Important edge-case contracts:
 
 ### Test Harness
 
-The E2E tests use a simulated target media server and a conformance client:
+The E2E tests double as validation harnesses for the reference implementation. They use a simulated target media server and a conformance client:
 
 - The target server accepts a response program per asset: repeated `304`s, replacement `200`s, deletion `404` / `410` steps, weighted transition windows, delays, and payload bodies.
 - The client sends unique fingerprints on every request and can vary method, range headers, `If-Range`, and browser validators.
@@ -296,6 +302,13 @@ CONFORMANCE_STRESS=1 CONFORMANCE_STRESS_COUNT=30000 CONFORMANCE_STRESS_CONCURREN
 
 The stress scenarios cover tens of thousands of unique fingerprints across shared media GIF IDs, renditions (`giphy`, `200`, `200w`, `100`), and file types: GIFs as `.gif`, `.mp4`, and `.webp`; Clips as `.mp4`; Stickers as `.gif` and `.webp`.
 
+To validate your own media proxy, adapt the harness model documented in [docs/media-proxy-conformance-harness.md](docs/media-proxy-conformance-harness.md): send each client request with a unique `x-giphy-conformance-fingerprint`, preserve that header on upstream validation/download requests, record target-server receipts, and compare planned fingerprints, client responses, upstream receipts, and final cache state. The lowest-friction path is to reuse the target server, synthetic client, scenario definitions, and assertion ledger under `test/support/`, then replace this repo's proxy startup with your proxy under test.
+
+Use these helper scripts when shaping or debugging another implementation:
+
+- `pnpm cache:summary [path/to/metadata.sqlite]` summarizes a local cache database into safe aggregate fixture shape data.
+- `pnpm media:characterize <media-url> [more URLs]` probes live media URL semantics such as `HEAD`, validators, negative responses, and range behavior without storing payload bytes.
+
 ### Browser Cache Validation
 
 To validate the browser cache layer in Chrome or Edge:
@@ -317,6 +330,17 @@ Expected browser behavior:
 
 If you do not see browser disk-cache hits or browser-facing `304` responses, first confirm `Disable cache` is off. If it is off, the most likely cause is a certificate error preventing Chrome from caching and reusing images for that local HTTPS origin. In that case, the proxy disk cache is still working and will still avoid upstream media downloads after origin revalidation, but browser-to-proxy transfers will continue and the TUI will overstate end-user network bandwidth saved. Use `pnpm tls:mkcert` or `TLS_CERT_FILE` / `TLS_KEY_FILE` to run with a locally trusted certificate when validating browser cache behavior.
 
+## Exercises Left To The Reader
+
+This reference implementation keeps several production concerns explicit instead of hiding them behind demo code:
+
+- Production deployment: packaging this behind a real CDN, load balancer, container image, process supervisor, or multi-region topology is out of scope.
+- Multi-node cache sharing: the demo uses local SQLite plus disk files. A production implementation needs its own answer for shared storage, eviction, backpressure, and node-local hot caches.
+- Policy integration: authentication, authorization, rate limiting, tenant isolation, abuse controls, and audit logging are not implemented here.
+- Observability: the TUI is useful for local demos, but production use needs metrics, tracing, alerting, and structured logs.
+- Standalone harness packaging: the conformance harness is written so another proxy can adapt it, but it is not currently published as a separate npm package or CLI.
+- Browser automation: browser-cache validation is documented as a manual Chrome/Edge workflow. A production-quality validation suite could add Playwright coverage for DevTools-visible disk-cache and `304` behavior.
+
 ## Terminal UI
 
 The TUI starts with the proxy and shows:

package.json

@@ -1,7 +1,9 @@
 {
   "name": "giphy-bandwidth-saver",
   "version": "0.1.0",
-  "private": true,
+  "description": "Reference implementation of a revalidating GIPHY media cache proxy.",
+  "license": "MIT",
+  "author": "GIPHY",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "engines": {