Skip to content
dc.
Back to selected work

Open-source project

TypeScript API Gateway: Routing and Resilience

A configuration-driven API gateway bringing routing, resilience, and observability into one system.

TypeScriptNode.jsNext.js

2 min read

Explore the system

At a glance

Organization
Independent open source
My role
Project author
Period
Open-source engineering
configuration-driven traffic management
Route. Protect. Observe.

Project capabilities are documented in the linked public repositories. Production adoption is not implied.

Gateway / request flow
GET /api/orders 200
ClientGatewayService
authrate limitcircuit breaker

The problem

Applications that talk to several services repeatedly need routing, authentication, traffic limits, and failure handling. Implementing those policies independently can create inconsistent behavior and duplicated work.

This project explores a shared entry point with typed, validated configuration and operational tooling.

The system

The gateway routes HTTP requests to upstream services. Its documented features include per-route authentication and rate limiting, circuit breaking, load balancing, timeouts, retry policies, caching, WebSocket proxying, and Prometheus metrics.

A Next.js dashboard provides visual configuration, while a CLI supports configuration workflows and OpenAPI import and export.

Decisions and tradeoffs

Configuration as a contract. Route validation happens before registration, making invalid configuration an explicit startup concern.

Policies at a shared boundary. Authentication, traffic control, and request tracing can be applied consistently before requests reach application services.

Operational behavior is part of the API. A timeout, an open circuit, and an authentication failure have different meanings. They need predictable responses and useful logs.

Distributed state needs explicit limits. The repository documents both local state and injectable shared stores, including limitations of last-write-wins circuit-breaker snapshots. Shared visibility does not imply atomic updates across processes.

Explore the failure path

The interactive example on this page illustrates a healthy circuit and an open circuit. It is a simplified simulation: it does not run the gateway or model its failure thresholds and recovery timers.

Evidence and next steps

The public repository includes architecture documentation, runnable examples, and test commands. Those are the starting point for inspecting the implementation. This portfolio does not claim independently verified throughput, uptime, or production adoption.

API Gateway

Explore the system

Follow three documented failure paths. These are illustrative traces based on repository examples, not requests to a running gateway.

Request path

  1. 01Client
  2. 02Route policies
  3. 03Upstream service
  4. 04Client response

The selected route applies its policies before proxying. Authentication can stop the request at the boundary; a timeout can terminate an upstream request; an open circuit avoids calling the failing service.

Authentication failure401

Illustrative trace

  1. GET /reports without x-api-key.
  2. The route requires an API key; the request is rejected.
  3. The upstream is not called. The client receives 401.

Published route configuration

[
  {
    "baseURL": "/reports",
    "proxy": {
      "target": "http://localhost:4005",
      "changeOrigin": true,
      "pathRewrite": {
        "^/reports": ""
      }
    },
    "auth": {
      "enabled": true,
      "strategy": "apiKey",
      "header": "x-api-key",
      "keys": [
        "key-service-alpha-123",
        "key-service-beta-456"
      ]
    }
  }
]
Upstream timeout504

Illustrative trace

  1. GET /slow is forwarded to the configured upstream.
  2. No response begins within the configured 100 ms.
  3. The upstream connection is aborted. The client receives 504.

Published route configuration

[
  {
    "baseURL": "/slow",
    "proxy": {
      "target": "http://localhost:4073",
      "pathRewrite": {
        "^/slow": ""
      },
      "timeout": 100
    }
  }
]
Open circuit503

Illustrative trace

  1. The /payments circuit is assumed open after its failure threshold is met.
  2. A subsequent request arrives before the 10,000 ms recovery window ends.
  3. The gateway skips the upstream. The client receives 503.

Published route configuration

[
  {
    "baseURL": "/payments",
    "proxy": {
      "target": "http://localhost:4006",
      "changeOrigin": true,
      "pathRewrite": {
        "^/payments": ""
      }
    },
    "circuitBreaker": {
      "threshold": 3,
      "timeout": 10000,
      "successThreshold": 1
    }
  }
]

Architecture decisions

Validated configuration
A typed route contract centralizes policies. The alternative is hand-written middleware per service, which offers flexibility but duplicates validation and policy wiring. Configuration still needs review and testing.
Separate failure controls
Timeouts bound waiting, while circuit breakers stop repeated calls to an unhealthy dependency. Retries are a separate choice: enabling them indiscriminately can amplify load or duplicate writes.

Recorded local run

From failure to recovery

Actual HTTP responses captured from the gateway and a local test service. The failure threshold is three, with a one-second recovery delay. The replay summarizes the steps; its timing is not the original request timing.

No audio. Captured on. Source for this run.

Captured responses and upstream calls
  1. Healthy service · HTTP 200

    Upstream requests: 1

                  {
      "service": "payments",
      "healthy": true
    }
                
  2. First failure · HTTP 500

    Upstream requests: 1

                  {
      "error": "Local demonstration failure"
    }
                
  3. Second failure · HTTP 500

    Upstream requests: 1

                  {
      "error": "Local demonstration failure"
    }
                
  4. Third failure · HTTP 500

    Upstream requests: 1

                  {
      "error": "Local demonstration failure"
    }
                
  5. Open circuit · HTTP 503

    Upstream requests: 0

                  {
      "error": "Service Unavailable",
      "message": "Circuit breaker open — upstream is not responding",
      "code": "CIRCUIT_OPEN"
    }
                
  6. Recovery probe · HTTP 200

    Upstream requests: 1

                  {
      "service": "payments",
      "healthy": true
    }
                

When a dependency fails

Illustrative simulation

Explore two circuit states. Actual thresholds, timers, and recovery probes are simplified here.

Response

200 OK

Circuit

Closed

The closed circuit forwards requests to the healthy upstream.

05 Let’s connect

Good work starts
with a conversation.

Have a challenging engineering problem, a role in mind, or an idea worth exploring? I’d like to hear about it.

derian.cordoba@icloud.com

Based in Nicaragua · Working with international teams

Let’s talk

Send a short introduction

Have a role, a collaboration, or a technical challenge in mind? Share a little context to start the conversation.

Opportunities · Collaboration · Engineering

Prefer to write directly?

derian.cordoba@icloud.com

All fields are required.

Your name, email, and message are processed by Netlify Forms to deliver your inquiry. Please avoid confidential information.