Classes

ServiceUrlBuilder

Service URL Builder for Kong Gateway routing

This class provides centralized URL construction for all FlowState services. It correctly handles Kong Gateway's path stripping behavior:

strip_path: false (path preserved): /auth/, /sync/, /api/*
strip_path: true (path removed): /mcp/, /obs/, /ams/*

Constructor

constructor(config?: ServiceUrlConfig)

Parameters:

Parameter	Type	Required	Description
`config`	`ServiceUrlConfig`	No	- Configuration options

Methods

getKongGatewayUrl

Get the base Kong Gateway URL (HTTP)

getKongGatewayUrl(): string

Returns:

string -

getKongGatewayHttpsUrl

Get the base Kong Gateway URL (HTTPS)

getKongGatewayHttpsUrl(): string

Returns:

string -

getRxdbReplicationUrl

Get RxDB Replication URL (Server-Sent Events + WebSocket)

Kong Route: /sync/* → rxdb-server:3002 (strip_path: false)

getRxdbReplicationUrl(collection: string, version: number): string

Parameters:

Parameter	Type	Required	Description
`collection`	`string`	Yes	- Collection name (e.g., 'tasks', 'projects')
`version`	`number`	Yes	- Schema version number

Returns:

string - Full replication URL

Examples:

builder.getRxdbReplicationUrl('tasks', 1)
// => 'http://localhost:7080/sync/tasks/1'

getRxdbRestUrl

Get RxDB REST API URL

Kong Route: /api/* → rxdb-server:3002 (strip_path: false)

getRxdbRestUrl(endpoint: string): string

Parameters:

Parameter	Type	Required	Description
`endpoint`	`string`	Yes	- API endpoint path (e.g., '/collections', '/health')

Returns:

string - Full REST API URL

Examples:

builder.getRxdbRestUrl('/collections')
// => 'http://localhost:7080/api/collections'

builder.getRxdbRestUrl('health')
// => 'http://localhost:7080/api/health'

getAuthUrl

Get Auth Service URL

Kong Route: /auth/* → auth-server:3001 (strip_path: false)

getAuthUrl(endpoint: string): string

Parameters:

Parameter	Type	Required	Description
`endpoint`	`string`	Yes	- Auth endpoint path (e.g., '/login', '/send-code', '/refresh')

Returns:

string - Full auth URL

Examples:

builder.getAuthUrl('/login')
// => 'http://localhost:7080/auth/login'

builder.getAuthUrl('send-code')
// => 'http://localhost:7080/auth/send-code'

getMcpUrl

Get MCP HTTP Service URL

Kong Route: /mcp/* → mcp-http:3100 (strip_path: true)

Important: Kong strips the /mcp prefix before forwarding to upstream. Client sends /mcp/tools, upstream receives /tools.

getMcpUrl(endpoint: string): string

Parameters:

Parameter	Type	Required	Description
`endpoint`	`string`	Yes	- MCP endpoint path (e.g., '/tools', '/health')

Returns:

string - Full MCP URL (includes /mcp prefix for Kong routing)

Examples:

builder.getMcpUrl('/tools')
// => 'http://localhost:7080/mcp/tools'
// Upstream receives: '/tools' (Kong strips '/mcp')

getObsUrl

Get Observability Server URL

Kong Route: /obs/* → obs-server:8080 (strip_path: true)

Important: Kong strips the /obs prefix before forwarding to upstream. Client sends /obs/events, upstream receives /events.

getObsUrl(endpoint: string): string

Parameters:

Parameter	Type	Required	Description
`endpoint`	`string`	Yes	- Observability endpoint path (e.g., '/events', '/health')

Returns:

string - Full observability URL (includes /obs prefix for Kong routing)

Examples:

builder.getObsUrl('/events')
// => 'http://localhost:7080/obs/events'
// Upstream receives: '/events' (Kong strips '/obs')

getAmsUrl

Get Agent Memory Service URL

Kong Route: /ams/* → ams:8000 (strip_path: true)

Important: Kong strips the /ams prefix before forwarding to upstream. Client sends /ams/v1/health, upstream receives /v1/health.

getAmsUrl(endpoint: string): string

Parameters:

Parameter	Type	Required	Description
`endpoint`	`string`	Yes	- AMS endpoint path (e.g., '/v1/health', '/v1/messages')

Returns:

string - Full AMS URL (includes /ams prefix for Kong routing)

Examples:

builder.getAmsUrl('/v1/health')
// => 'http://localhost:7080/ams/v1/health'
// Upstream receives: '/v1/health' (Kong strips '/ams')

getOAuthDiscoveryUrl

Get OAuth Discovery URL

Kong Route: /.well-known/* → auth-server:3001 (strip_path: false)

getOAuthDiscoveryUrl(): string

Returns:

string - OAuth authorization server discovery URL

Examples:

builder.getOAuthDiscoveryUrl()
// => 'http://localhost:7080/.well-known/oauth-authorization-server'

Examples:

const builder = new ServiceUrlBuilder({
  kongGatewayUrl: 'http://localhost:7080'
});

// RxDB replication (path preserved)
const replicationUrl = builder.getRxdbReplicationUrl('tasks', 1);
// => 'http://localhost:7080/sync/tasks/1'

// Auth endpoint (path preserved)
const authUrl = builder.getAuthUrl('/login');
// => 'http://localhost:7080/auth/login'

// MCP tool (path stripped by Kong)
const mcpUrl = builder.getMcpUrl('/tools');
// => 'http://localhost:7080/mcp/tools'
// Upstream receives: '/tools' (path stripped)