Home
Complete JavaScript/TypeScript SDK for Runtime Debug Control Protocol v1.0
New: Read the in-depth RDCP Technical Analysis and Architecture Overview rdcp-technical-analysis
RDCP stands for Runtime Debug Control Protocol — a standardized HTTP-based protocol for controlling configurable behaviors in distributed applications at runtime.
While RDCP started as a protocol for debug logging control, it has evolved into enterprise-grade runtime system control infrastructure. The protocol defines 5 required endpoints (discovery, control, status, health, plus protocol discovery) that allow external tools to enable/disable categorized behaviors without requiring application restarts.
- Kubernetes = Container Control Plane
- Istio = Service Mesh Control Plane
- RDCP = Application Behavior Control Plane
Once services are RDCP-compliant:
- ANY admin tool can work with ANY service
- ANY incident response system can control ANY application
- ANY compliance system can audit ANY behavior
- ANY monitoring tool can dynamically enable debugging
HTTP → Web communication standard
gRPC → RPC communication standard
OTEL → Observability data standard
RDCP → Operational control standard
RDCP aims to serve as a general-purpose operational control primitive that complements monitoring and configuration systems. It fills a practical gap between observing systems and safely changing their behavior at runtime.
See also: Universal Service Discovery — how services advertise capabilities for environment-wide inventory and tooling.
🔧 Performance & Profiling Controls
- Enable/disable CPU profiling and memory allocation tracking
- Control database query timing and expensive instrumentation
- Toggle stack trace collection and adjust sampling rates
🚀 Feature Flag Management
- Runtime enable/disable of experimental features
- A/B testing controls adjustable without deployments
- Circuit breaker controls for external services
🔒 Security & Audit Controls
- Detailed security logging for auth attempts and authorization failures
- PII logging levels for compliance requirements
- Request/response logging for security analysis
⚙️ Development vs Production Behaviors
- Switch between dev-friendly and production-safe error messages
- Control mock vs real external API usage
- Toggle local vs cloud storage backends
📊 Resource Usage Controls
- Enable/disable caching mechanisms and connection pool behaviors
- Control sync vs async processing modes
- Toggle retry mechanisms and timeout behaviors
🌐 Third-party Integration Controls
- Enable/disable specific external service integrations
- Toggle between primary and backup service endpoints
- Control service discovery and load balancing behaviors
The RDCP SDK provides a complete implementation of RDCP v1.0, making it easy to add these standardized runtime control capabilities to any JavaScript/Node.js application with zero overhead when controls are disabled.
# Server SDK (adapters, endpoints, auth)
npm install @rdcp.dev/server
# Client SDK (fetch-based)
npm install @rdcp.dev/client
# Core (protocol constants, error codes, schemas)
npm install @rdcp.dev/coreconst { adapters, auth } = require('@rdcp.dev/server')
const express = require('express')
const app = express()
app.use(express.json())
// Add RDCP endpoints with authentication
const rdcpMiddleware = adapters.express.createRDCPMiddleware({
authenticator: auth.validateRDCPAuth
})
app.use(rdcpMiddleware)
app.listen(3000)
// ✅ RDCP endpoints now available:
// GET /.well-known/rdcp
// GET /rdcp/v1/discovery
// POST /rdcp/v1/control
// GET /rdcp/v1/status
// GET /rdcp/v1/health- RDCP v1.0/v2.0 delivers a complete runtime control ecosystem:
- @rdcp.dev/client 1.0.0 — control applications (Node 18+, native fetch)
- @rdcp.dev/server 2.1.0 — target applications (adapters/endpoints/auth)
- @rdcp.dev/core 1.0.0 — shared protocol definitions (schemas, constants, error codes)
- OpenTelemetry integration — end-to-end trace correlation of control operations
- End-to-end developer workflows: programmatic control via client SDK (no more curl-first examples)
- Updated install snippets and docs; demo app integration with client SDK is tracked
Previous highlights (2025-09-20)
- New error code: RDCP_REQUEST_ID_INVALID (400) for malformed X-RDCP-Request-ID headers
- Adapters now always echo the correlation header as X-Request-Id on all RDCP responses; a UUID is generated when the client does not supply X-RDCP-Request-ID
- RateLimit draft-7 headers (RateLimit, RateLimit-Policy, RateLimit-Remaining, RateLimit-Reset) are emitted consistently across adapters when enabled; 429 responses include Retry-After and structured error details
- Audit failure behavior now supports ignore, warn, and fail modes. In warn mode, responses include Warning: 199 rdcp "audit-write-failed" when the audit sink fails
See: Error-Responses.md (error codes, rate-limit details) and Basic-Usage.md (capabilities configuration and examples).
- Quick-Start-Guide — fresh-clone setup, build, and launch instructions (demo + admin)
- Architecture-Overview — how the core, client, admin UI, and admin app fit together
- Demo-Scenarios — guided flows for Admin UI and Client SDK
- Validation-Scripts — headless data-layer validation (discovery/status + AdminUISpec)
- Troubleshooting — build/ESM/Jest configuration issues and fixes
- AI-Agent-Quick-Reference — copy/paste setup for agents and automation
- RDCP-Demo-App — one-command local demo with Dependencies graph
- Implementation-Status — current state, demos, and observability
- Proof-of-Capabilities - Test Evidence and Demo Commands
- One-liner:
npm run demo:proof(start demo app first:npm run dev --prefix packages/rdcp-demo-app)
- **Client-SDK-Demo
- Installation - Install and setup the RDCP SDK
- Basic-Usage - Quick integration examples for all supported frameworks
- Rate-Limiting - Configuration, standard headers, and structured error details
- Monitoring - /status measured metrics and optional Prometheus /metrics
- Express.js Integration - Complete Express.js middleware setup
- Fastify Integration - Fastify plugin and middleware patterns
- Koa Integration - Koa middleware integration
- Next.js Integration - Next.js App Router implementation
- Trace-Propagation-Demo — upstream → rdcp-demo-app with cross-service tracing
- OpenTelemetry-Overview - Enterprise-grade trace correlation with RDCP debug logs
- Framework Examples - Production-ready integrations for Express, Next.js, Fastify, Koa
- Migration Guides - Step-by-step migration from existing logging to RDCP + OpenTelemetry
- Backend Configurations - Working examples for Jaeger, DataDog, New Relic, and more
- DataDog Quickstart - 10-minute path to Datadog APM + RDCP correlation
- New Relic Quickstart - 10-minute path to New Relic + RDCP correlation
- Performance Analysis - Benchmarks, overhead measurement, and production tuning
- Security and Compliance - Data protection, audit trails, retention, and regulatory mapping
- Operational Production Guide - Authentication at scale, rate limiting, multi-tenancy
- Enterprise-Deployment-Patterns - Kubernetes, service mesh, and collector architectures
- Authentication-Setup - 3 security levels: Basic, Standard, Enterprise
- Multi-Tenancy - Tenant isolation and context management
- Error-Responses - Standardized error schema, codes, and assertions
- Testing-Helpers - JWT scopes, mTLS simulation, hybrid and tenant patterns
- JWKS - Enable JWKS, security notes, and HS256 → RS256 migration
- Logging - Debug-by-default with env-gated warnings
- Migration-Guide - Migrate from manual RDCP implementation to SDK
- API-Reference - Use the client SDK to consume RDCP endpoints
- PROTOCOL-COMPLIANCE-REPORT - RDCP v1.0 protocol compliance details
- API Documentation - Complete API reference and endpoint specifications
- Error Handling - Standard error codes and response formats
- Primary spec: RDCP Protocol Specification
- Implementation guide: RDCP Implementation Guide
Notes:
- These are authoritative but dense. Most users should start with the Quick Reference and Demo App pages above.
- TESTING-SUMMARY - Run and develop tests for the SDK
- how-to-contribute-to-the-docs - Development setup and contribution guidelines
- Release-Policy - SemVer rules, tagging, release notes, retagging criteria, checklist
- AI-Development-Guidelines - How WARP.md and warp-generic.md guide AI and human development
✅ Complete RDCP v1.0 Protocol Compliance
✅ All 3 Security Levels - Basic (API Key), Standard (JWT), Enterprise (mTLS)
✅ Multi-Framework Support - Express, Fastify, Koa, Next.js
✅ Client & Server SDKs - Full bidirectional RDCP implementation
✅ Multi-Tenancy Support - Organization, namespace, and process isolation
✅ Zero Configuration - Works out of the box with sensible defaults
✅ TypeScript Support - Full type definitions included
Status: Level 2: Standard (RDCP v1.0)
- ✅ All required endpoints implemented with correct response formats
- ✅ 3 authentication security levels supported
- ✅ Multi-tenancy with standard header support
- ✅ Protocol-compliant error handling
- ✅ Client & Server SDKs; Temporary controls (TTL) promoted to core (server + adapters + client)
- ✅ Testing coverage: 201 passing tests across 25 test suites
- ℹ️ Demo app includes examples for rate limiting and audit trail
Last updated: 2025-09-20
See PROTOCOL-COMPLIANCE-REPORT for detailed analysis.
- Node.js: 16.0.0 or higher
- Frameworks: Express 4.18+, Fastify 4.0+, or Koa 2.0+
Apache License 2.0 — see LICENSE file for details.
- Edit pages under wiki/ in this repository and open a PR
- Keep examples copy/pasteable and tested against the demo app
- Prefer linking to existing pages over duplicating content
- For advanced protocol details, link to docs/rdcp-protocol-specification.md and docs/rdcp-implementation-guide.md
- Read: AI-Agent-Quick-Reference
- Try: RDCP Demo App (In-Memory Jaeger)
- Integrate: Installation → Basic-Usage
- Explore: Trace-Propagation-Demo
- Deep dive: Protocol references in docs/ (advanced)
- RDCP Protocol Specification