cachegate 1.0.0

package/.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+npm-debug.log
+.env
+.env.local
+.git
+.gitignore
+test/
+.github/
+data/
+*.md
+!README.md

package/.env.example

@@ -0,0 +1,112 @@
+# cachegate environment template
+# Copy the values you need into your real .env file.
+# NEVER commit .env to Git.
+
+PORT=4000
+
+# Required: protects the router from unauthorized use. The server
+# refuses to start without this UNLESS ALLOW_INSECURE_LOCAL_DEV=true
+# (below) is explicitly set - a missing key never silently means "no
+# auth enforced."
+# Generate with: openssl rand -hex 32
+MODEL_ROUTER_INTERNAL_KEY=your-random-internal-key
+
+# Optional: skip the MODEL_ROUTER_INTERNAL_KEY requirement above, for a
+# throwaway LOCAL instance only. Never set this on anything reachable
+# from outside your own machine.
+# ALLOW_INSECURE_LOCAL_DEV=true
+
+# Required (at least one provider key - Anthropic, OpenAI, or both).
+# The model itself is named PER REQUEST in the API call's own "model"
+# field (see README's "Usage" section), not configured here - there is
+# no ANTHROPIC_MODEL/OPENAI_MODEL env var to set.
+ANTHROPIC_API_KEY=sk-ant-api03-...
+
+# Also required for the semantic cache's embeddings, regardless of
+# which provider actually serves chat requests - it's the only
+# embedding backend implemented (see semanticCache.js / README).
+# OPENAI_API_KEY=sk-proj-...
+
+# Optional: which OpenAI embedding model the semantic cache uses.
+# Only matters if OPENAI_API_KEY is set. Default is a good balance of
+# cost and quality; change only if you know you want a different one.
+# EMBEDDING_MODEL=text-embedding-3-small
+
+# Optional: Redis for response caching (strongly recommended for cost savings)
+# Local development:
+# REDIS_URL=redis://localhost:6379
+# Render Key Value:
+# REDIS_URL=rediss://default:PASSWORD@HOST:PORT
+
+# Optional: persistent metrics storage (see metrics.js's own comment).
+# Unset (the default) keeps metrics as local JSONL files, which don't
+# survive a restart/redeploy on most hosts - fine for a standalone
+# deployment with no database of its own. Set this to a real Postgres
+# connection string to persist metrics there instead.
+# DATABASE_URL=postgres://user:pass@host:5432/dbname
+#
+# MEMOCODE_ROUTER_DATABASE_URL does the exact same thing and takes
+# priority over DATABASE_URL if both are set - use this instead when
+# embedding cachegate inside an app that already has its own
+# DATABASE_URL pointed at a different database (so the two never
+# collide), or just to keep this router's own connection string
+# explicitly distinct from whatever else reads DATABASE_URL in your stack.
+# MEMOCODE_ROUTER_DATABASE_URL=postgres://user:pass@host:5432/dbname
+
+# Optional: where JSONL metrics files live, if Postgres isn't
+# configured. Despite the name, this now names a DIRECTORY (kept for
+# backward compatibility with older configs that pointed it at a
+# single file - see metrics.js's own comment). Defaults to ./data
+# next to this file.
+# METRICS_LOG_PATH=./data
+
+# Optional: how long metrics history is kept before pruneOlderThan()'s
+# scheduled daily job deletes it. Default 90 days deliberately matches
+# /dashboard/data's own longest supported range - pruning any sooner
+# would make its "Last 90 days" option quietly lie.
+# METRICS_RETENTION_DAYS=90
+
+# Optional: semantic cache tuning (all have sane defaults - see README's
+# "Two kinds of cache hit" section before changing these).
+# SEMANTIC_CACHE_ENABLED=false          # hard off-switch, even with a key configured
+# SEMANTIC_CACHE_THRESHOLD=0.93         # cosine similarity floor for a match
+# SEMANTIC_CACHE_MAX_CANDIDATES=200     # per-model list cap (brute-force scan size)
+# SEMANTIC_CACHE_TTL_SECONDS=3600
+
+# Optional: override the default "router:" virtual-model tiers
+# (router.js's own DEFAULT_TIERS) with your own JSON, e.g. to add a
+# model, swap a provider, or define a new tier name entirely. Must be
+# valid JSON matching the shape:
+# {"router:fast-cheap":[{"provider":"openai","model":"gpt-4o-mini"}]}
+# Invalid JSON logs a warning and falls back to the built-in defaults
+# rather than crashing.
+# ROUTER_TIERS_JSON={"router:fast-cheap":[...]}
+
+# Optional: routing strategy for "router:" virtual models (router.js).
+# See README's "Where this leaves things" section for what each one
+# actually does before changing this - there's no blended cost/latency
+# score, only these three explicit options.
+# ROUTER_STRATEGY=cost                        # default: cheapest healthy candidate
+# ROUTER_STRATEGY=latency                     # fastest healthy candidate, cost only as a tiebreaker
+# ROUTER_STRATEGY=latency-guarded-cost        # cheapest healthy candidate, excluding any that's too much slower than the fastest known one
+# ROUTER_LATENCY_GUARD_MULTIPLIER=3           # only used by latency-guarded-cost
+
+# Optional: rate limiting on /v1/* (server.js). Default 300 requests
+# per 60 seconds - shared across EVERY caller of this router combined,
+# not per end user if you're fronting it with your own per-user auth.
+# See server.js's own comment above the rate limiter for the reasoning.
+# RATE_LIMIT_MAX=300
+# RATE_LIMIT_WINDOW_MS=60000
+
+# Optional: separate, more generous rate limit for the read-only
+# aggregate endpoints (/stats, /dashboard/data) - lower stakes than
+# /v1 (no provider spend on the line) but still real server work.
+# Shares RATE_LIMIT_WINDOW_MS above.
+# READ_RATE_LIMIT_MAX=120
+
+# Optional: max JSON body size accepted on /v1/* (server.js). Default
+# 2mb comfortably covers even a very long text conversation - this
+# router doesn't support image/multimodal content, so there's no
+# legitimate reason for a much larger payload. Raise only if you have
+# a specific reason to expect longer request bodies.
+# JSON_BODY_LIMIT=2mb

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Something isn't working the way it should
+title: ''
+labels: bug
+assignees: ''
+---
+
+**What happened**
+A clear description of the actual behavior.
+
+**What you expected instead**
+
+**Steps to reproduce**
+1.
+2.
+3.
+
+**Environment**
+- cachegate version:
+- Node version:
+- Deployment: standalone / embedded in another app / Docker
+- Redis: version, and whether it's configured at all (some features
+  degrade cleanly without it — see README's "Features")
+
+**Relevant config**
+Which env vars are set (names only — **never paste real API keys, the
+internal key, or a database URL here**): e.g. `ROUTER_STRATEGY=cost`,
+`SEMANTIC_CACHE_ENABLED=true`, `DATABASE_URL` set (Postgres) vs. unset
+(JSONL).
+
+**Logs**
+Relevant server console output, with any secret values redacted.

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+# NOTE (remove before step 15/16 ships): the URL below has a placeholder
+# "OWNER" - fill in the real GitHub org/username once the public repo
+# actually exists.
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/OWNER/cachegate/security/advisories/new
+    about: Do not open a public issue for a vulnerability - use private vulnerability reporting instead. See SECURITY.md.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest something this project should do
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Before filing — is this in scope?**
+Read `README.md`'s "What this is NOT" section first. Login, billing,
+multi-tenant key custody, or a hosted-service feature will be closed as
+out of scope regardless of how it's proposed — that functionality
+belongs to a separate closed product built on this engine, not to this
+engine. Everything else (routing, caching, provider support, the
+dashboard, operational tooling) is fair game.
+
+**What problem does this solve?**
+Describe the actual pain, not just the feature - "I need X because Y
+currently forces me to Z."
+
+**What would the ideal solution look like?**
+A sketch is fine - an API shape, a new env var, a CLI flag.
+
+**Alternatives considered**
+What are you doing today without this? Is there a workaround?
+
+**Additional context**
+Anything else - a link to how a similar tool does this, a real
+production scenario this came up in.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## What changed and why
+
+<!-- The problem this solves, not just the diff. If it fixes a bug,
+say how you found and verified it. -->
+
+## Scope check
+
+- [ ] I've read `README.md`'s "What this is NOT" section and confirmed
+      this doesn't add login, billing, multi-tenant key custody, or a
+      hosted-service feature.
+
+## Testing
+
+<!-- What you ran, and what it proved. "npm test passes" is fine for a
+small change; describe manual verification for anything that couldn't
+be covered by the existing suite (e.g. a real provider call). -->
+
+- [ ] `npm test` passes locally
+- [ ] Added/updated tests for the behavior this changes, or explained
+      why that's not practical (e.g. it needs a live provider call)
+
+## Anything reviewers should look at closely
+
+<!-- Optional - a tricky edge case, a tradeoff you're not fully sure
+about, a place you deviated from an existing pattern in the codebase. -->

package/.github/workflows/test.yml

@@ -0,0 +1,63 @@
+name: Tests
+
+# Runs on every push and PR - unlike this monorepo's own root
+# .github/workflows/e2e.yml (currently workflow_dispatch-only), this
+# is a public OSS repo once extracted: a green check on every PR IS
+# the trust signal step 8 of OPEN_SOURCE_ROADMAP.md exists for, so
+# automatic triggers are the whole point here, not something to dial
+# back to manual.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    # metrics-postgres.test.js needs a REAL reachable Postgres - it
+    # fails loudly (ECONNREFUSED) rather than skipping if one isn't
+    # running, by design (see that file's own header comment). Values
+    # here match its own hardcoded fallback connection string exactly
+    # (MEMOCODE_ROUTER_TEST_DATABASE_URL's default), so no extra env
+    # wiring is needed below.
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: dryrun
+          POSTGRES_DB: router_metrics_dryrun
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    strategy:
+      # Multiple Node versions, not just one: package.json declares
+      # "engines": {"node": ">=18.0.0"} - running the suite against all
+      # three actually backs that claim instead of just asserting it.
+      matrix:
+        node-version: ['18.x', '20.x', '22.x']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      # semanticCache.test.js spawns its own throwaway redis-server
+      # process directly (a real instance, not a mock) - ubuntu-latest
+      # doesn't ship the binary, so it has to be installed explicitly.
+      # This is NOT the same thing as the Postgres service above: that
+      # test connects to an already-running external service, this one
+      # starts and stops its own process on a random port.
+      - name: Install redis-server
+        run: sudo apt-get update && sudo apt-get install -y redis-server
+
+      - run: npm ci
+      - run: npm test

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,66 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+our community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political
+  attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, pull
+requests, discussions), and also applies when an individual is
+officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported to the maintainers via the contact method listed in
+`SECURITY.md`. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to cachegate
+
+Thanks for considering it. This is a small, deliberately focused
+project — read the scope note below before writing code, it'll save
+you a round-trip.
+
+## Scope — read this first
+
+`README.md`'s "What this is NOT" section is the actual contract, not
+just a marketing caveat: **no login, no billing, no multi-tenant key
+custody, no hosted service** live in this repository, and a PR adding
+any of those will be closed regardless of how well it's built — that
+functionality belongs to a separate, closed product built on top of
+this engine, not this engine itself. This isn't a licensing
+restriction (MIT permits building any of that — see `LICENSE`); it's
+that this repository specifically isn't going to grow into a hosted
+competitor to its own paid product, so a PR heading that direction
+gets closed here regardless of quality, not merged and then diverged
+from later.
+
+Everything else — routing strategies, cache behavior, provider
+support, the dashboard, bug fixes — is fair game.
+
+## Running it locally
+
+```bash
+git clone <this-repo-url>
+cd cachegate
+npm install
+cp .env.example .env   # then fill in a real key for at least one provider
+npm start
+```
+
+## Running the tests
+
+```bash
+npm test
+```
+
+This runs Node's built-in test runner (`node --test`) across every file
+in `test/`. A few things worth knowing before you add to it:
+
+- **No test here calls a real provider API.** That needs live keys and
+  real spend, which isn't reasonable to require of a contributor or a
+  CI run. Provider-facing logic (`providers/anthropic.js`,
+  `providers/openai.js`) is tested by factoring the pure,
+  non-network parts (see `applyStreamEvent`/`applyStreamChunk`) out
+  into directly-testable functions with canned input — follow that
+  pattern for new provider logic rather than trying to mock the HTTP
+  layer.
+- **Tests need to be genuinely isolated.** Several existing tests reset
+  `METRICS_LOG_PATH` to a fresh temp file per test (see
+  `router.test.js`'s `freshModules` helper) specifically because
+  `metrics.js` reads its config once at require time. If your test
+  writes metrics, don't assume a clean slate — either isolate it the
+  same way, or place it deliberately last in its file if it needs to
+  run after everything else that depends on a clean state (see
+  `server.test.js`'s own comment on this for a worked example).
+- All tests must pass before a PR is reviewed. If a test is failing for
+  a reason unrelated to your change, say so explicitly in the PR rather
+  than silently working around it — that's a real bug worth its own
+  issue.
+
+## Opening a PR
+
+- Explain the *why*, not just the *what* — a one-line "fixes X" is
+  fine for a trivial fix, but anything behavioral should say what
+  problem it solves and how you verified the fix, the same standard
+  this codebase's own commit history holds itself to.
+- If you're touching `router.js`'s scoring logic, `failover.js`'s
+  retry logic, or anything else with existing inline documentation
+  explaining a past decision (search the file for "why" before
+  changing something that looks arbitrary) — it's very likely not
+  arbitrary. If you disagree with the reasoning, say so in the PR;
+  don't just silently remove it.
+- Small, focused PRs review faster than large ones bundling several
+  unrelated changes.
+
+**How merges actually work here, stated plainly:** this repository is
+mirrored out from a private internal monorepo where day-to-day
+development happens, rather than the other way around. Your PR gets
+reviewed and, once approved, merged here on GitHub like normal — but
+it's also manually reapplied on the internal side afterward, through
+that project's own review process, rather than auto-syncing. In
+practice this means a short delay between "merged here" and "in the
+next internal release," not a rejection — you'll see it land in a
+tagged release once that happens.
+
+## Reporting a bug vs. reporting a security issue
+
+Regular bugs: open a GitHub issue. Security vulnerabilities (anything
+that could let a request bypass auth, leak another deployment's data,
+or exhaust resources in a way rate limiting doesn't already cover): see
+`SECURITY.md` instead — please don't file those as public issues.

package/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+# The official Node images already ship a non-root "node" user (uid 1000) -
+# use it instead of running as root, standard practice for a public image.
+RUN chown -R node:node /app
+USER node
+EXPOSE 4000
+# No curl/wget in the slim base image - Node's own http module does the
+# check instead. Uses the real GET /health endpoint (public, no auth,
+# exists specifically for this).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:'+(process.env.PORT||4000)+'/health',(r)=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"
+CMD ["node", "server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MemoCode
+
+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.