@armored1486/api-gateway-core

Serverless-native API Gateway toolkit — token-bucket rate limiting, RS256 JWT auth, and typed errors. Pure logic with zero AWS imports, so it drops into any runtime (Lambda, Node, edge). Where express-rate-limit + jsonwebtoken leave you wiring storage and error shapes by hand, this ships a pluggable atomic store and a machine-readable error contract out of the box.

npm install @armored1486/api-gateway-core

Requirements

• Node ≥ 22
• ESM only — ships as ES modules (import); there is no CommonJS (require) build.

What's inside

| Module | What it does | |---|---| | CircuitBreaker | Rolling failure window, cooldown and bounded recovery probes | | RateLimiter | Token bucket rate limiter with pluggable store (in-memory, DynamoDB, Redis) | | validateToken | RS256 JWT validation with pluggable JWKS fetcher | | validate | Zod-based request validation with typed errors | | AppError | Typed error hierarchy — HTTP status + machine-readable code |

RateLimiter

import { RateLimiter } from "@armored1486/api-gateway-core";
import type { RateLimiterStore, BucketState } from "@armored1486/api-gateway-core";

const store: RateLimiterStore = new MyStore(); // implement get/set
const limiter = new RateLimiter(store, { capacity: 100, refillRate: 10 });

const result = await limiter.consume("api-key-abc");
// { allowed: true, remaining: 99 }
// { allowed: false, remaining: 0, retryAfter: 5.2 }

The store is pluggable — implement get(key), set(key, state), and optionally atomicConsume(key, tokens, capacity, refillRate) using any backend (DynamoDB, Redis, PostgreSQL). The optional atomicConsume folds read-modify-write into one round trip and prevents TOCTOU race conditions under concurrency. The rate limiter is pure logic with zero runtime dependencies.

The official Redis adapter is a separate workspace package; see installation, VPC requirements and integration tests. It never adds Redis dependencies to core.

Circuit breaker (core 2.2.0)

import { CircuitBreaker, MemoryCircuitBreakerStore } from "@armored1486/api-gateway-core";

const breaker = new CircuitBreaker(new MemoryCircuitBreakerStore(), {
  failureThreshold: 0.5,
  minimumCalls: 10,
  windowSize: 20,
  cooldownMs: 30_000,
  halfOpenMaxProbes: 1,
});
const response = await breaker.execute(
  "upstream",
  () => fetch("https://api.example.com/health"),
  () => true, // classify rejected calls as upstream failures
  response => response.status >= 500,
);

An open circuit throws CircuitOpenError (503, CIRCUIT_OPEN), whose toLambdaResponse() includes Retry-After in seconds. HTTP 4xx responses do not open the circuit with the predicate above. The gateway also counts body-read failures and network timeouts. Rate limiting happens before the breaker check.

State and concurrency coordination are local to one breaker instance/warm Lambda environment. Cold starts begin closed. A shared store alone does not provide distributed probe coordination. The first completed successful recovery probe closes the circuit; later results from the old generation are ignored. Keep the number of upstream keys bounded when using the in-memory store.

JWT validation

import { validateToken } from "@armored1486/api-gateway-core";
import type { JwksFetcher } from "@armored1486/api-gateway-core";

const fetcher: JwksFetcher = {
  async getKey(kid: string) {
    // Fetch from JWKS endpoint, return the public key as a PEM (SPKI) string
    return "-----BEGIN PUBLIC KEY-----...";
  },
};

const payload = await validateToken(token, {
  issuer: "https://auth.example.com",
  audience: "api-gateway",
  maxTokenAge: 86_400, // 24h — reject tokens older than this (since iat)
  clockTolerance: 30,  // 30s clock skew
}, fetcher);
// { sub: "user-123", iss: "...", aud: "...", exp: 1712345678, ... }

Only RS256 is accepted; tokens with any other alg are rejected.

Validation

import { validate } from "@armored1486/api-gateway-core";
import { z } from "zod";

const schema = z.object({ name: z.string(), age: z.number() });
const data = validate(schema, req.body);
// data is typed as { name: string; age: number }

Error codes

Every error extends AppError and carries a machine-readable code. These codes are a public API contract.

| Class | HTTP | Code | |---|---|---| | UnauthorizedError | 401 | UNAUTHORIZED | | ThrottledError | 429 | THROTTLED | | ValidationError | 400 | VALIDATION_ERROR | | InternalError | 500 | INTERNAL_ERROR | | CircuitOpenError | 503 | CIRCUIT_OPEN |

import { AppError } from "@armored1486/api-gateway-core";

try {
  await doSomething();
} catch (err) {
  if (err instanceof AppError) {
    return err.toLambdaResponse();
    // {
    //   statusCode: 429,
    //   headers: { "Content-Type": "application/json", "Retry-After": "5.2" },
    //   body: '{"error":"THROTTLED","message":"Rate limit exceeded"}'
    // }
  }
}

InternalError always serializes a generic body — the underlying cause is preserved on the instance for logging only, never sent to the client.

Performance

The rate limiter is pure in-memory arithmetic — it does no I/O of its own. Latency depends on the injected store. The DynamoDB adapter performs a read and conditional write; Redis performs one atomic EVAL round trip. Performance targets require measurements of the actual deployment.

Bundle size

Under 50 KB gzipped (published tarball ≈ 10 KB). Two runtime dependencies: Zod and jose. The AWS SDK is an optional peer dependency, only pulled in by the DynamoDB store in the template.

Deploy the full gateway

The SST template currently provisions a single regional API Gateway REST API, Lambda proxy/authorizer and DynamoDB table in production. Other stages use a Function URL. It does not provision Global Tables replicas or latency-based Route 53 routing. See the deployment guide.

npx sst deploy --stage production

Monitoring and response cache

Handlers emit CloudWatch EMF under namespace ApiGateway, with only Stage as a dimension. Gateway metrics: RequestCount, ThrottledCount, CircuitOpenCount, UpstreamErrorCount, GatewayLatencyMs, and UpstreamLatencyMs when an upstream attempt occurs. Authorizer metrics: AuthorizedCount, UnauthorizedCount, AuthorizerLatencyMs.

The stack defines alarms for handler P99 >150ms over five one-minute periods, upstream errors >1% and throttling >5% of gateway requests over one minute. Notification destinations must be connected by the operator. Handler latency excludes API Gateway transport and authorizer time; it is not end-to-end latency.

Authorizer cache effectiveness can be estimated using Lambda Invocations versus API Gateway Count over the same protected traffic, stage, region and period. It is not an exact hit ratio; see the guide for exclusions.

Response caching remains disabled after the cache spike: identity, query/header variation, error caching and upstream Cache-Control handling need a proven route contract. No cache cluster is created.

Development

npm ci
npm run build:all
npm run typecheck
npm run typecheck --workspaces
npx eslint .
npm test
# Include real Redis integration tests:
REDIS_URL=redis://127.0.0.1:16389 npm test

Core releases use vX.Y.Z; Redis releases use store-redis-vX.Y.Z. Both must match manifest versions. Core 2.2.0 and Redis 1.0.0 are prepared, not published.

Links

• Changelog
• Security policy

License

MIT — see LICENSE.