@pipeline-builder/api-server

@pipeline-builder/api-server

View documentation

Express server infrastructure for Pipeline Builder: app factory, middleware (CORS, Helmet, rate limiting, idempotency, ETag), request context, route wrappers, health-check helpers, and SSE support.

Internal workspace package — consumed by other packages via workspace:*. Not published or used standalone.

Responsibilities

Assembles the standardized HTTP runtime shared by every backend service: a configured Express app factory, request-context middleware (identity + structured logging), org-scoped rate limiting, idempotency and ETag handling, quota enforcement, async route wrappers with consistent error mapping, health/readiness checks, metrics and OpenTelemetry tracing, and a Server-Sent Events connection manager. Builds on @pipeline-builder/api-core for auth, responses, and logging.

Key exports

App factory & lifecycle (./api)

Export	Purpose
createApp	Configured Express app: CORS, Helmet (strict CSP), gzip/deflate compression, org-keyed rate limiting (shared Redis store when redisUrl is set), /health, /ready, /warmup, /metrics, and Swagger UI + OpenAPI at /docs. Fails fast if JWT_SECRET is unset.
startServer, runServer	Server lifecycle with graceful shutdown

Middleware (./api)

Export	Purpose
attachRequestContext, createRequestContext	Attach identity + logging (RequestContext) to each request
requireOrgId	Validate the x-org-id header is present
checkQuota	Quota enforcement middleware
etagMiddleware	Conditional GET (304 Not Modified) support
idempotencyMiddleware, createMemoryStore, createRedisIdempotencyStore	Idempotency-key handling with pluggable stores

Route helpers (./api)

Export	Purpose
withRoute	Wrap async handlers with context extraction, orgId validation, and error mapping
getContext	Retrieve RequestContext from an Express request
createProtectedRoute, createAuthenticatedWithOrgRoute	Composable auth/org middleware chains

Health, quota & observability (./api)

Export	Purpose
postgresHealthCheck	Returns { postgres: 'connected' | 'disconnected' }
mongoHealthCheck	Returns { mongodb: 'connected' | 'unknown' | 'disconnected' } from mongoose readyState
incrementQuotaFromCtx	Increment a quota counter from the route context
metricsMiddleware, metricsHandler, incCounter, observe, setGauge	Prometheus metrics collection and /metrics handler
initTracing, currentTraceId	OpenTelemetry tracing init and current trace ID

Server-Sent Events (./http)

Export	Purpose
SSEManager	Connection manager for streaming logs/events to clients

Usage

import { createApp, withRoute, getContext } from '@pipeline-builder/api-server';
import { requireAuth, sendSuccess } from '@pipeline-builder/api-core';

const { app } = createApp({ serviceName: 'plugin-service' });

app.get(
  '/plugins',
  requireAuth(),
  withRoute(async (req, res) => {
    const { orgId, logger } = getContext(req);
    logger.info('listing plugins', { orgId });
    return sendSuccess(res, await plugins.findByOrg(orgId));
  }),
);

Development

pnpm build   # projen build (compile + lint + test)
pnpm test    # run the Jest test suite

License

Apache-2.0. See LICENSE.