@epicdm/flowstate-url-builder

Centralized URL builder for Kong Gateway routing in FlowState. Provides a consistent interface for constructing service URLs with proper path handling for Kong Gateway's path stripping behavior.

Installation

yarn add @epicdm/flowstate-url-builder

Overview

FlowState uses Kong Gateway as a single API entry point for all services. Kong Gateway routes requests to different upstream services based on path prefixes, with some routes using path stripping and others preserving the full path.

This package provides a ServiceUrlBuilder class that abstracts the complexity of constructing correct URLs for each service, ensuring consistent routing across all FlowState packages.

Kong Gateway Routes

| Client Request | Kong Route | Upstream Service | Path Stripping | |----------------|------------|------------------|----------------| | http://localhost:7080/.well-known/* | /.well-known/* | auth-server:3001 | ❌ (preserved) | | http://localhost:7080/auth/* | /auth/* | auth-server:3001 | ❌ (preserved) | | http://localhost:7080/sync/* | /sync/* | rxdb-server:3002 | ❌ (preserved) | | http://localhost:7080/api/* | /api/* | rxdb-server:3002 | ❌ (preserved) | | http://localhost:7080/mcp/* | /mcp/* | mcp-http:3100 | ✅ (stripped) | | http://localhost:7080/obs/* | /obs/* | obs-server:8080 | ✅ (stripped) | | http://localhost:7080/ams/* | /ams/* | ams:8000 | ✅ (stripped) |

Path Stripping Explained:

• strip_path: false - Full path is preserved (e.g., /auth/login → /auth/login)
• strip_path: true - Route prefix is removed (e.g., /mcp/tools → /tools)

Usage

Basic Usage

import { createServiceUrlBuilder } from '@epicdm/flowstate-url-builder';

// Create URL builder with Kong Gateway URL
const urlBuilder = createServiceUrlBuilder({
  kongGatewayUrl: 'http://localhost:7080'
});

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

// RxDB REST API (path preserved)
const restUrl = urlBuilder.getRxdbRestUrl('/collections');
// → http://localhost:7080/api/collections

// Auth endpoints (path preserved)
const loginUrl = urlBuilder.getAuthUrl('/login');
// → http://localhost:7080/auth/login

// MCP tools (path stripped)
const mcpUrl = urlBuilder.getMcpUrl('/tools');
// → http://localhost:7080/mcp/tools (becomes /tools upstream)

// Observability (path stripped)
const obsUrl = urlBuilder.getObsUrl('/events');
// → http://localhost:7080/obs/events (becomes /events upstream)

// Agent Memory Service (path stripped)
const amsUrl = urlBuilder.getAmsUrl('/v1/health');
// → http://localhost:7080/ams/v1/health (becomes /v1/health upstream)

Docker Internal Network

When running inside Docker containers, use the internal network address:

const urlBuilder = createServiceUrlBuilder({
  kongGatewayUrl: 'http://kong:8000'  // Docker internal network
});

HTTPS Support

For production environments with HTTPS:

const urlBuilder = createServiceUrlBuilder({
  kongGatewayUrl: 'http://localhost:7080',
  kongGatewayHttpsUrl: 'https://localhost:7443'
});

// Get HTTPS URL
const secureUrl = urlBuilder.getAuthHttpsUrl('/login');
// → https://localhost:7443/auth/login

OAuth Discovery

Get the OAuth discovery endpoint:

const discoveryUrl = urlBuilder.getOAuthDiscoveryUrl();
// → http://localhost:7080/.well-known/oauth-authorization-server

API Reference

createServiceUrlBuilder(config?: ServiceUrlConfig): ServiceUrlBuilder

Factory function to create a ServiceUrlBuilder instance.

Parameters:

• config (optional): Configuration object
  • kongGatewayUrl (string): Kong Gateway HTTP URL (default: http://localhost:7080)
  • kongGatewayHttpsUrl (string): Kong Gateway HTTPS URL (default: https://localhost:7443)

ServiceUrlBuilder Methods

RxDB Methods (path preserved - strip_path: false)

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

Constructs RxDB replication URL for SSE-based sync.

Example:

urlBuilder.getRxdbReplicationUrl('tasks', 1)
// → http://localhost:7080/sync/tasks/1

getRxdbRestUrl(endpoint: string): string

Constructs RxDB REST API URL.

Example:

urlBuilder.getRxdbRestUrl('/tasks-rest/0/query')
// → http://localhost:7080/api/tasks-rest/0/query

getRxdbRestBaseUrl(): string

Gets the base URL for RxDB REST API.

Example:

urlBuilder.getRxdbRestBaseUrl()
// → http://localhost:7080/api

Auth Methods (path preserved - strip_path: false)

getAuthUrl(endpoint: string): string

Constructs authentication endpoint URL (HTTP).

Example:

urlBuilder.getAuthUrl('/login')
// → http://localhost:7080/auth/login

getAuthHttpsUrl(endpoint: string): string

Constructs authentication endpoint URL (HTTPS).

Example:

urlBuilder.getAuthHttpsUrl('/login')
// → https://localhost:7443/auth/login

getOAuthDiscoveryUrl(): string

Gets the OAuth discovery endpoint URL.

Example:

urlBuilder.getOAuthDiscoveryUrl()
// → http://localhost:7080/.well-known/oauth-authorization-server

MCP Methods (path stripped - strip_path: true)

getMcpUrl(endpoint: string): string

Constructs MCP (Model Context Protocol) endpoint URL.

Note: Kong strips /mcp prefix before forwarding.

Example:

urlBuilder.getMcpUrl('/tools')
// → http://localhost:7080/mcp/tools
// Upstream receives: /tools

Observability Methods (path stripped - strip_path: true)

getObsUrl(endpoint: string): string

Constructs observability service endpoint URL.

Note: Kong strips /obs prefix before forwarding.

Example:

urlBuilder.getObsUrl('/events')
// → http://localhost:7080/obs/events
// Upstream receives: /events

Agent Memory Service Methods (path stripped - strip_path: true)

getAmsUrl(endpoint: string): string

Constructs Agent Memory Service endpoint URL.

Note: Kong strips /ams prefix before forwarding.

Example:

urlBuilder.getAmsUrl('/v1/health')
// → http://localhost:7080/ams/v1/health
// Upstream receives: /v1/health

Environment Variables

Host Applications (CLI, Next.js, Electron)

KONG_GATEWAY_URL=http://localhost:7080
KONG_GATEWAY_HTTPS_URL=https://localhost:7443

Docker Containers (MCP Server)

KONG_GATEWAY_URL=http://kong:8000

Integration Examples

With RxDB Replication

import { createServiceUrlBuilder } from '@epicdm/flowstate-url-builder';

class ReplicationManager {
  private urlBuilder: ServiceUrlBuilder;

  constructor(serverUrl: string) {
    this.urlBuilder = createServiceUrlBuilder({
      kongGatewayUrl: serverUrl
    });
  }

  initializeReplication(collection: string, schemaVersion: number) {
    const replicationUrl = this.urlBuilder.getRxdbReplicationUrl(
      collection,
      schemaVersion
    );

    return replicateRxCollection({
      collection,
      replicationIdentifier: `${collection}-replication`,
      url: replicationUrl,
      // ...
    });
  }
}

With Auth Service

import { createServiceUrlBuilder } from '@epicdm/flowstate-url-builder';

class AuthService {
  private urlBuilder: ServiceUrlBuilder;

  constructor(serverUrl: string) {
    this.urlBuilder = createServiceUrlBuilder({
      kongGatewayUrl: serverUrl
    });
  }

  async login(email: string, code: string) {
    const response = await fetch(this.urlBuilder.getAuthUrl('/login'), {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, code })
    });

    return response.json();
  }
}

With MCP Client

import { createServiceUrlBuilder } from '@epicdm/flowstate-url-builder';

class MCPClient {
  private baseUrl: string;

  constructor(kongGatewayUrl: string) {
    const urlBuilder = createServiceUrlBuilder({ kongGatewayUrl });
    // Note: getMcpUrl returns full URL with /mcp prefix
    // Since Kong strips /mcp, we can use the base URL directly
    this.baseUrl = urlBuilder.getMcpUrl('');
  }

  async callTool(toolName: string, args: any) {
    const response = await fetch(`${this.baseUrl}/tools/${toolName}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(args)
    });

    return response.json();
  }
}

Testing

Run unit tests:

yarn test

The package includes comprehensive unit tests covering:

• URL construction for all services
• Path stripping behavior
• Edge cases (leading/trailing slashes, empty strings)
• Docker network URLs
• HTTPS support

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { ServiceUrlBuilder, ServiceUrlConfig } from '@epicdm/flowstate-url-builder';

const config: ServiceUrlConfig = {
  kongGatewayUrl: 'http://localhost:7080',
  kongGatewayHttpsUrl: 'https://localhost:7443'
};

const builder: ServiceUrlBuilder = createServiceUrlBuilder(config);

License

Apache-2.0

Related Packages

• @epicdm/flowstate-app-framework - Uses URL builder for replication and auth
• @epicdm/flowstate-cli - Uses URL builder for CLI operations
• @epicdm/flowstate-mcp - Uses URL builder for MCP server
• @epicdm/flowstate-auth-core - Authentication services

Contributing

See the main FlowState repository for contribution guidelines.