@teliagen/federation

Federation and proxy generation for Teliagen microservices.

Overview

@teliagen/federation enables seamless microservices communication:

• Proxy Generation – Auto-generate typed proxies for remote actions
• Type Mirroring – Mirror schemas and types across services
• Zero-Import Federation – Use remote actions like local code
• Contract Sync – Fetch and cache service contracts
• Dependency Resolution – Automatic cascading dependency resolution

Installation

npm install @teliagen/federation
# or
pnpm add @teliagen/federation

How It Works

1. Service A exposes actions via ServerContractSync feature
2. Service B syncs from A via configuration
3. FederationGenerator creates typed proxies in .teliagen/
4. Service B imports proxies like local code

┌─────────────┐     Contract JSON      ┌─────────────┐
│  Service A  │ ──────────────────────>│  Service B  │
│             │                        │             │
│  - Actions  │                        │  .teliagen/ │
│  - Schemas  │                        │  - Proxies  │
│  - Types    │                        │  - Types    │
└─────────────┘                        └─────────────┘

Configuration

Service A (Provider)

// teliagen.config.ts
import { defineConfig, ServerContractSync } from '@teliagen/commons';

export default defineConfig({
  server: {
    name: 'auth-service',
    port: 3001
  },
  features: [
    ServerContractSync({
      endpoint: '/teliagen/server-contract',
      apiKey: process.env.CONTRACT_API_KEY,
      expose: {
        includeEntities: true
      }
    })
  ]
});

Service B (Consumer)

// teliagen.config.ts
import { defineConfig } from '@teliagen/commons';

export default defineConfig({
  server: {
    name: 'main-service',
    port: 3000
  },
  services: [
    {
      name: 'auth',
      mode: 'remote',
      url: 'http://localhost:3001',
      apiKey: process.env.AUTH_API_KEY,
      contract: {
        endpoint: '/teliagen/server-contract',
        apiKey: process.env.CONTRACT_API_KEY
      },
      sync: {
        modules: [
          {
            module: 'auth',
            proxy: true,
            actions: '*',
            schemas: '*',
            types: '*'
          }
        ]
      }
    }
  ]
});

Sync Configuration

Sync Everything

sync: true
// or
sync: '*'

Selective Sync

sync: {
  common: {
    schemas: ['UserSchema', 'TokenSchema'],
    types: '*',
    services: []
  },
  modules: [
    {
      module: 'auth',
      proxy: true,
      providers: [
        {
          name: 'AuthActions',
          actions: ['login', 'register', 'refreshToken']
        }
      ],
      schemas: '*',
      types: '*'
    },
    {
      module: 'users',
      proxy: true,
      actions: '*',
      schemas: ['UserOutput']
    }
  ]
}

Proxy Options

sync: {
  proxy: true,  // Global proxy setting
  modules: [
    {
      module: 'auth',
      proxy: true,  // Module-level override
      providers: [
        {
          name: 'AuthActions',
          proxy: false,  // Disable proxy for this provider
          actions: '*'
        }
      ]
    }
  ]
}

Generated Output

After running teliagen dev or teliagen build:

.teliagen/
└── auth/
    ├── proxies/
    │   └── auth.proxy.ts       # Action proxies
    ├── schemas/
    │   ├── LoginInput.ts       # Input schemas
    │   └── UserOutput.ts       # Output schemas
    ├── types/
    │   └── AuthTypes.ts        # Type definitions
    └── index.ts                # Barrel export

Generated Proxy

// .teliagen/auth/proxies/auth.proxy.ts
import { TeliagenHost } from '@teliagen/server';
import { LoginInput, LoginOutput } from '../schemas';

export class AuthProxyActions {
  /**
   * Authenticates a user and returns access tokens.
   */
  static async login(input: LoginInput): Promise<LoginOutput> {
    const host = TeliagenHost.getInstance();
    return host.execute('auth', 'login', input, {
      module: 'auth',
      provider: 'AuthActions'
    });
  }

  static async register(input: RegisterInput): Promise<UserOutput> {
    const host = TeliagenHost.getInstance();
    return host.execute('auth', 'register', input, {
      module: 'auth',
      provider: 'AuthActions'
    });
  }

  // ... more proxies
}

Using Proxies

// Import generated proxy
import { AuthProxyActions } from '.teliagen/auth';

// Use like local code
@ActionProvider('orders', 'OrderActions')
class OrderActions {
  @Action('createOrder')
  async createOrder(@Input() input: CreateOrderInput) {
    // Call remote auth service transparently
    const user = await AuthProxyActions.getUser(input.userId);
    
    if (!user) {
      throw new Error('User not found');
    }
    
    return Order.create({
      ...input,
      userEmail: user.email
    });
  }
}

FederationGenerator API

For programmatic usage:

import { FederationGenerator } from '@teliagen/federation';
import { loadConfig } from '@teliagen/commons';

const { config, root } = await loadConfig();
const generator = new FederationGenerator(root, config);

// Generate all federation proxies
await generator.generate();

Generator Methods

interface FederationGenerator {
  constructor(projectRoot: string, config: TeliagenConfig);
  
  // Main generation
  generate(): Promise<void>;
  
  // Service-specific generation
  generateServiceContent(
    service: ServiceConfig, 
    metadata: any, 
    outputDir: string
  ): Promise<void>;
}

Metadata Contract

Services expose contracts with this structure:

{
  "server": {
    "name": "auth-service",
    "version": "1.0.0"
  },
  "modules": [
    {
      "name": "auth",
      "providers": [
        {
          "name": "AuthActions",
          "actions": [
            {
              "name": "login",
              "input": { "$ref": "LoginInput" },
              "output": { "$ref": "LoginOutput" }
            }
          ]
        }
      ]
    }
  ],
  "schemas": {
    "LoginInput": {
      "properties": {
        "email": { "type": "string" },
        "password": { "type": "string" }
      }
    }
  },
  "types": {},
  "externalDependencies": {}
}

Cross-Service Execution

The generated proxies use TeliagenHost.execute():

// Low-level API
const host = TeliagenHost.getInstance();

const result = await host.execute(
  'auth',           // Service name
  'login',          // Action name
  { email, pass },  // Input
  {
    module: 'auth',
    provider: 'AuthActions'
  }
);

Local Service Federation

For monorepo setups, use local mode:

services: [
  {
    name: 'users',
    mode: 'local',
    path: '../packages/users',
    sync: '*',
    expose: true
  }
]

Requirements

• Node.js >= 18.0.0
• @teliagen/server >= 0.1.0

Related Packages

• @teliagen/server – TeliagenHost runtime
• @teliagen/commons – Configuration types
• @teliagen/cli – CLI triggers generation

Documentation

For full documentation, visit docs.teliagen.org.

License

Apache-2.0