Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
@carbon/kv
Redis client (ioredis) and rate limiting library. Used for permission caching, login rate limiting, and general key-value storage.
Always
- Import the singleton Redis client via
import { redis } from "@carbon/kv"— it's a global singleton with lazy connect and retry logic. - The singleton is resilience-wrapped (
src/resilient.ts): Redis is a cache, never the source of truth, so when it's unreachable commands fail soft instead of throwing — a read resolvesnull(a collection resolves[]), a write resolvesnull, and a pipeline.exec()resolves[]. Justawait redis.get(...)normally; treatnullas a cache miss and read through to the DB. Do not wrap call sites in try/catch for connectivity — that's already handled. Each command also has aREDIS_TIMEOUT_MScap so a hung Redis can't stall a request. - Use
Ratelimitclass with static factory methods:Ratelimit.fixedWindow(),Ratelimit.slidingWindow(), orRatelimit.tokenBucket(). When Redis is downRatelimit.limit()fails open (returnssuccess: true) — a cache outage never blocks auth. - Handle rate limit responses: check
response.success— caller is responsible for returning 429 when!success. - Requires
REDIS_URLenv var — throws at import if not set.
Ask First
- Changing Redis connection config (retry strategy,
maxRetriesPerRequest,lazyConnect) — affects all Redis consumers. - Adding new rate limiting algorithms or modifying Lua scripts (
scripts.ts).
Never
- Create additional Redis client instances — use the global singleton to avoid connection pool exhaustion.
- Store large blobs in Redis — it's for caching, rate limiting, and small state only.
Validation Commands
pnpm --filter @carbon/kv test # Runs ratelimit + cache tests (uses ioredis-mock)
pnpm --filter @carbon/kv typecheck
Key Exports
| Export | Provides |
|---|---|
redis |
Global ioredis singleton (lazy connect, 3 retries, offline queue), resilience-wrapped to fail soft when Redis is unreachable |
Ratelimit |
Rate limiter class with limit(), blockUntilReady(), getRemaining(), resetUsedTokens(), refund() (sliding window only: give back a token limit() consumed, for consume-before-verify callers such as MES console pin-in) |
Ratelimit.fixedWindow(tokens, window) |
Fixed window algorithm (simple, low memory) |
Ratelimit.slidingWindow(tokens, window) |
Sliding window (smoother, prevents boundary bursts) |
Ratelimit.tokenBucket(refillRate, interval, maxTokens?) |
Token bucket (allows controlled bursts) |
redisFlagsStore |
The FlagsStore for initFlags (@carbon/env/flags.server): the shared flags document per source in the hash flags:<scope> (body, etag, fetchedAt, at most 1 MB) and the refresh lease flags:<scope>:refresh |
Duration type |
Time duration strings like "10 s", "1 m", "1 h" |
Cross-References
packages/auth/— uses Redis for permission claim caching (permissions:${userId}keys)packages/database/src/ratelimit.ts— separate API key rate limiting via Postgres RPC (not Redis)packages/env/— providesREDIS_URL