endpoint-routing · diff
git:20251007.b9f65b6 to v2.0.0
130 added, 75 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
+ version: "2.0.0"
description: Endpoint routing patterns and request handling conventions
globs: src/index.ts,src/**/*.ts
+ lastUpdated: "2025-10-08"
+ dependencies: ["quality-standards", "api-patterns"]
---
# Endpoint Routing Rules
## Main Entry Point
All HTTP requests are handled in [src/index.ts](mdc:src/index.ts) via the `fetch()` handler.
## Request Flow Pattern
```typescript
- 1. Generate requestId: Date.now().toString(36)
+ import { generateRequestId, createOPTIONSResponse, createJSONResponse } from '../utils/request';
+ import { createLogger } from '../utils/logger';
+
+ 1. Generate requestId: generateRequestId()
2. Parse URL: new URL(request.url)
- 3. Log request details with requestId
- 4. Handle CORS preflight (OPTIONS)
+ 3. Log request details with StructuredLogger
+ 4. Handle CORS preflight: createOPTIONSResponse()
5. Route by pathname
- 6. Return response with CORS headers
+ 6. Return response: createJSONResponse() (includes CORS)
```
## Endpoint Categories
### Core System Endpoints (4)
**Pattern:** Exact pathname match
```typescript
if (url.pathname === '/health') {
// Health check - used by all dashboards
// Returns: { status, version, timestamp, requestId, duration }
}
if (url.pathname === '/logs') {
// Centralized logging - used by browser extension
// POST: Receives log batches from extension
}
if (url.pathname === '/diagnostics') {
// System diagnostics - used by setup wizard, health monitor
// Returns: bindings status, KV status, last checks
}
if (url.pathname === '/system-status') {
// Detailed status - used by dashboard stats
// Returns: uptime, memory, KV records, health indicators
}
```
**Used By:** All dashboards, monitoring tools, browser extension
---
### BetTicker Endpoints (3+)
**Pattern:** Exact pathname or prefix match
```typescript
if (url.pathname === '/cloud/api/Manager/getBetTicker') {
// Transparent proxy + KV interception
// Handler: handleBetTickerInterception()
// Location: src/interceptors/bet-ticker-sniffer.ts
// Returns: Original API response (with side-effect KV storage)
}
if (url.pathname.startsWith('/interceptor/')) {
// BetTicker history/analysis API
// Handler: handleInterceptorAPI()
// Routes:
// - /interceptor/history?limit=100
// - /interceptor/response?key=...
// - /interceptor/stats
}
```
**Used By:** Browser extension, all dashboards
**Documentation:** [docs/BET_TICKER_SNIFFER.md](mdc:docs/BET_TICKER_SNIFFER.md)
---
### MCP Protocol Endpoints (2+)
**Pattern:** Exact pathname or prefix match
```typescript
if (url.pathname === '/mcp') {
// JSON-RPC 2.0 MCP protocol endpoint
// Handler: handleMCPRequest()
// Location: src/mcp/server.ts
// Methods: initialize, tools/list, tools/call
}
if (url.pathname.startsWith('/tools/')) {
// Intelligence tools API (13 tools)
// Handler: handleMCPTools()
// Routes:
// - /tools/getBettingExposure
// - /tools/getCLV
// - /tools/getSharpScore
// - /tools/getHoldPercentage
}
```
**Used By:** Claude Desktop, AI assistants, Dashboard Pro
**Documentation:** [docs/MCP_ENDPOINTS.md](mdc:docs/MCP_ENDPOINTS.md)
---
## Required Patterns
### 1. Request ID Tracking
**ALWAYS generate and use a request ID:**
```typescript
- const requestId = Date.now().toString(36);
- console.log(`[${requestId}] 📥 Incoming request:`, { method, url });
+ import { generateRequestId } from '../utils/request';
+ import { createLogger } from '../utils/logger';
+
+ const requestId = generateRequestId();
+ const logger = createLogger(request);
+ logger.info('request_received', { method, url });
```
**Use in responses:**
```typescript
- return new Response(JSON.stringify({ requestId, ...data }), {
- headers: { 'Content-Type': 'application/json' }
- });
+ import { createJSONResponse } from '../utils/request';
+
+ return createJSONResponse({ requestId, ...data });
```
---
### 2. CORS Headers
**ALWAYS include CORS headers for dashboard access:**
```typescript
- const corsHeaders = {
- 'Access-Control-Allow-Origin': '*',
- 'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
- 'Access-Control-Allow-Headers': 'Content-Type',
- };
+ import { CORS_HEADERS, createOPTIONSResponse, createJSONResponse } from '../utils/request';
+
+ // CORS headers available as constant
+ // No need to define inline
```
**Handle OPTIONS preflight:**
```typescript
if (request.method === 'OPTIONS') {
- return new Response(null, { headers: corsHeaders });
+ return createOPTIONSResponse();
}
```
+ **Use in responses:**
+ ```typescript
+ // Automatic with createJSONResponse
+ return createJSONResponse({ data });
+
+ // Or manually
+ return new Response(data, { headers: { ...CORS_HEADERS } });
+ ```
+
---
### 3. Error Handling
**Standardized error response:**
```typescript
+ import { createErrorResponse } from '../utils/request';
+ import { createLogger } from '../utils/logger';
+
+ const logger = createLogger(request);
+
try {
// Handler logic
} catch (error) {
- console.error(`[${requestId}] ❌ Error:`, error);
- return new Response(JSON.stringify({
- error: 'Error type',
- message: error instanceof Error ? error.message : 'Unknown error',
- requestId,
- }), {
- status: 500,
- headers: { 'Content-Type': 'application/json', ...corsHeaders }
- });
+ logger.error('handler_failed', {
+ errorType: error instanceof Error ? error.name : 'Unknown'
+ }, error as Error);
+
+ return createErrorResponse(
+ error instanceof Error ? error.message : 'Unknown error',
+ 500,
+ 'HANDLER_ERROR',
+ requestId
+ );
}
```
---
### 4. Performance Logging
**Log request duration:**
```typescript
- const startTime = Date.now();
+ import { performanceTimer } from '../utils/logger';
+
+ const logger = createLogger(request);
+ const timer = performanceTimer(logger, 'request_handler');
+
// ... handle request
- const duration = Date.now() - startTime;
- console.log(`[${requestId}] ✅ Completed in ${duration}ms`);
+
+ timer.end({ requestId, statusCode: 200 });
```
---
## Handler Functions
### Pattern: Separate Functions for Complex Routes
```typescript
+ import { createJSONResponse, createErrorResponse, generateRequestId } from '../utils/request';
+ import { createLogger } from '../utils/logger';
+
// In main fetch handler:
if (url.pathname === '/diagnostics') {
return handleDiagnostics(request, env, ctx);
}
// Separate handler function:
async function handleDiagnostics(
- request: Request,
- env: Env,
+ request: Request,
+ env: Env,
ctx: ExecutionContext
): Promise<Response> {
- const corsHeaders = { /* CORS headers */ };
+ const requestId = generateRequestId();
+ const logger = createLogger(request);
+
try {
+ logger.info('diagnostics_started', { requestId });
// Handler logic
- return new Response(JSON.stringify(data), { headers: corsHeaders });
+ return createJSONResponse({ data, requestId });
} catch (error) {
- // Error handling
+ logger.error('diagnostics_failed', { requestId }, error as Error);
+ return createErrorResponse('Diagnostics failed', 500, 'DIAGNOSTICS_ERROR', requestId);
}
}
```
**Current handlers in [src/index.ts](mdc:src/index.ts):**
- `handleMCPTools()` - Routes to intelligence tools
- `handleDiagnostics()` - System diagnostics
- `handleLogs()` - Log retrieval
- `handleSystemStatus()` - Detailed status
- `handleInterceptorAPI()` - BetTicker history/analysis
---
## Integration Points
### Dashboard Hub Integration
**Location:** [dashboards/index.html](mdc:dashboards/index.html)
**Connected Endpoints:**
```javascript
const WORKER_URL = 'https://betting-brain-v3.nolarose1968-806.workers.dev';
// System status
fetch(`${WORKER_URL}/health`)
// Data count and last update
fetch(`${WORKER_URL}/interceptor/history?limit=100`)
```
**Auto-refresh:** 30 seconds
---
### Browser Extension Integration
**Location:** [browser-extension/](mdc:browser-extension/)
**Connected Endpoints:**
```javascript
// Log forwarding (background.js)
fetch(`${WORKER_URL}/logs`, {
method: 'POST',
body: JSON.stringify({ logs, sessionId })
})
// BetTicker interception (content.js)
fetch(`${WORKER_URL}/cloud/api/Manager/getBetTicker`, {
method: 'POST',
body: originalRequestBody
})
```
---
## Queue & Cron Integration
### Queue Consumers
**Handler:** `async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext)`
**Routes:**
```typescript
if (batch.queue === 'line-ingress') {
await handleLineIngress(message, env, ctx);
}
if (batch.queue === 'steam-webhook') {
await handleSteamWebhook(message, env, ctx);
}
```
**Location:** [src/queues/](mdc:src/queues/)
---
### Scheduled Jobs
**Handler:** `async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext)`
**Routes:**
```typescript
if (event.cron === '0 * * * *') {
// Hourly sharp calculation
await handleSharpCalculation(env, ctx);
}
if (event.cron === '*/30 * * * * *') {
// 30-second exposure calculation (actually every minute due to CF limitations)
await handleExposureCalculation(env, ctx);
}
```
**Location:** [src/schedules/](mdc:src/schedules/)
**Documentation:** [docs/DATABASE_CRON_VERIFICATION.md](mdc:docs/DATABASE_CRON_VERIFICATION.md)
---
## Adding New Endpoints
### 1. Core/System Endpoint
**Add to main fetch handler:**
```typescript
+ import { generateRequestId } from '../utils/request';
+ import { createLogger } from '../utils/logger';
+
+ const requestId = generateRequestId();
+ const logger = createLogger(request);
+
if (url.pathname === '/my-endpoint') {
- console.log(`[${requestId}] 🎯 My endpoint accessed`);
+ logger.info('endpoint_accessed', { endpoint: '/my-endpoint', requestId });
return handleMyEndpoint(request, env, ctx);
}
```
**Create handler function:**
```typescript
+ import {
+ generateRequestId,
+ createJSONResponse,
+ createErrorResponse
+ } from '../utils/request';
+ import { createLogger } from '../utils/logger';
+
async function handleMyEndpoint(
request: Request,
env: Env,
ctx: ExecutionContext
): Promise<Response> {
- const corsHeaders = {
- 'Access-Control-Allow-Origin': '*',
- 'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
- 'Access-Control-Allow-Headers': 'Content-Type',
- 'Content-Type': 'application/json'
- };
+ const requestId = generateRequestId();
+ const logger = createLogger(request);
try {
+ logger.info('handler_started', { requestId });
// Your logic here
- return new Response(JSON.stringify({ data }), { headers: corsHeaders });
+ return createJSONResponse({ data, requestId });
} catch (error) {
- console.error('My endpoint error:', error);
- return new Response(JSON.stringify({
- error: 'Failed',
- message: error instanceof Error ? error.message : 'Unknown error'
- }), {
- status: 500,
- headers: corsHeaders
- });
+ logger.error('handler_failed', { requestId }, error as Error);
+ return createErrorResponse(
+ error instanceof Error ? error.message : 'Unknown error',
+ 500,
+ 'HANDLER_ERROR',
+ requestId
+ );
}
}
```
---
### 2. Intelligence Tool Endpoint
**Add to handleMCPTools switch:**
```typescript
case 'getMyTool':
return getMyTool(request, env);
```
**Create tool file:**
- Location: [src/tools/intelligence/getMyTool.ts](mdc:src/tools/intelligence/)
- Export: `export async function getMyTool(request: Request, env: Env): Promise<Response>`
**Add to MCP tools list:**
- Location: [src/mcp/tools.ts](mdc:src/mcp/tools.ts)
- Add tool definition with schema
---
### 3. MCP Handler
**Create handler:**
- Location: [src/mcp/handlers/myHandler.ts](mdc:src/mcp/handlers/)
- Export function matching tool name
**Register in toolRegistry:**
- Location: [src/mcp/toolRegistry.ts](mdc:src/mcp/toolRegistry.ts)
- Add case statement
**Documentation:** [docs/MCP_ENDPOINTS.md](mdc:docs/MCP_ENDPOINTS.md)
---
## Performance Expectations
| Endpoint Type | Expected Response Time | Complexity |
|--------------|----------------------|------------|
| `/health` | 5-20ms | Low |
| `/interceptor/history` | 50-300ms | Medium |
| `/mcp` (tools/list) | 20-100ms | Low |
| `/mcp` (tools/call) | 100-500ms | High |
| `/tools/*` | 50-150ms | Low-Medium |
**CPU Limit:** 50ms per request (from wrangler.toml)
---
## Testing Endpoints
### Local Development
```bash
# Start worker
bun run dev
# Test health
curl http://localhost:8787/health
# Test with request ID
curl -H "X-Request-ID: test123" http://localhost:8787/diagnostics
# Test MCP
curl -X POST http://localhost:8787/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### Production
```bash
# Deploy
wrangler deploy --env production
# Test
curl https://betting-brain-v3.nolarose1968-806.workers.dev/health
# Monitor
wrangler tail --env production
```
---
## Common Pitfalls
### ❌ DON'T
```typescript
// No CORS headers
return new Response(JSON.stringify(data));
// No request ID tracking
console.log('Request received');
+ // Inline CORS headers
+ const corsHeaders = { 'Access-Control-Allow-Origin': '*' };
+
+ // Manual request ID
+ const requestId = Date.now().toString(36);
+
// No error handling
const result = await riskyOperation();
return new Response(JSON.stringify(result));
-
- // Duplicate endpoint handling
- if (url.pathname === '/logs') { /* handler 1 */ }
- // ... later ...
- if (url.pathname === '/logs') { /* handler 2 - DUPLICATE! */ }
```
### ✅ DO
```typescript
- // With CORS headers
- return new Response(JSON.stringify(data), {
- headers: { ...corsHeaders, 'Content-Type': 'application/json' }
- });
+ import {
+ generateRequestId,
+ createJSONResponse,
+ createErrorResponse,
+ CORS_HEADERS
+ } from '../utils/request';
+ import { createLogger } from '../utils/logger';
- // With request ID
- const requestId = Date.now().toString(36);
- console.log(`[${requestId}] Request received`);
+ // With proper utilities
+ const requestId = generateRequestId();
+ const logger = createLogger(request);
+ logger.info('request_received', { requestId });
// With error handling
try {
const result = await riskyOperation();
- return new Response(JSON.stringify({ requestId, result }), {
- headers: { ...corsHeaders }
- });
+ return createJSONResponse({ requestId, result });
} catch (error) {
- console.error(`[${requestId}] Error:`, error);
- return new Response(JSON.stringify({
- error: 'Failed',
- requestId,
- message: error instanceof Error ? error.message : 'Unknown'
- }), {
- status: 500,
- headers: { ...corsHeaders }
- });
+ logger.error('operation_failed', { requestId }, error as Error);
+ return createErrorResponse(
+ error instanceof Error ? error.message : 'Unknown',
+ 500,
+ 'OPERATION_ERROR',
+ requestId
+ );
}
```
---
+ ## Related Rules
+
+ - [Quality Standards](mdc:.cursor/rules/quality-standards.mdc) - Code quality standards ⭐ **NEW**
+ - [API Patterns](mdc:.cursor/rules/api-patterns.mdc) - API validation & error handling
+ - [Cloudflare Workers](mdc:.cursor/rules/cloudflare-workers.mdc) - Workers patterns
+ - [MCP Integration](mdc:.cursor/rules/mcp-integration.mdc) - MCP patterns
+
## Related Documentation
- - **[Cloudflare Workers Rules](.cursor/rules/cloudflare-workers.mdc)** - Workers patterns
- - **[MCP Integration Rules](.cursor/rules/mcp-integration.mdc)** - MCP patterns
+ - **[docs/QUALITY_STANDARDS.md](mdc:docs/QUALITY_STANDARDS.md)** - Complete quality guide ⭐ **NEW**
+ - **[src/utils/request.ts](mdc:src/utils/request.ts)** - Request utilities ⭐ **NEW**
+ - **[src/utils/logger.ts](mdc:src/utils/logger.ts)** - Logging utilities ⭐ **NEW**
+ - **[src/shared/constants.ts](mdc:src/shared/constants.ts)** - All constants ⭐ **NEW**
- **[docs/ENDPOINT_DASHBOARD_INTEGRATION.md](mdc:docs/ENDPOINT_DASHBOARD_INTEGRATION.md)** - Complete endpoint guide
- **[docs/SYSTEM_INTEGRATION_MAP.md](mdc:docs/SYSTEM_INTEGRATION_MAP.md)** - System architecture
---
- **Total Endpoints:** 10+ core endpoints + 13 MCP tools
+ **Total Endpoints:** 10+ core endpoints + 13 MCP tools
**Status:** Production-ready with full CORS, error handling, and logging
+ **Last Updated:** 2025-10-08