@consonant/proto-relayer

Shared Protocol Buffer definitions for Consonant Relayer gRPC streaming.

Overview

This package provides type-safe TypeScript interfaces for bidirectional gRPC streaming between:

• Relayer (cluster-resident agent)
• Backend (self-hosted control plane)

Installation

npm install @consonant/proto-relayer

Usage

Server (Backend)

import { 
  RelayerServiceService,
  ServerMessage,
  ClientMessage,
  StreamInitResponse
} from '@consonant/proto-relayer';
import * as grpc from '@grpc/grpc-js';

// Implement the service
const relayerService: RelayerServiceService = {
  OpenStream: (stream: grpc.ServerDuplexStream<ClientMessage, ServerMessage>) => {
    // Handle bidirectional stream
    stream.on('data', (message: ClientMessage) => {
      if (message.initRequest) {
        // Handle init
        const response: ServerMessage = {
          initResponse: {
            accepted: true,
            message: 'Connected',
            timestamp: new Date(),
            serverVersion: '1.0.0'
          }
        };
        stream.write(response);
      }
    });
  }
};

// Create server
const server = new grpc.Server();
server.addService(RelayerServiceService, relayerService);

Client (Relayer)

import {
  RelayerServiceClient,
  ClientMessage,
  ServerMessage,
  credentials,
  GrpcMetadata
} from '@consonant/proto-relayer';

// Create client
const client = new RelayerServiceClient(
  'backend.company.com:50051',
  credentials.createSsl()
);

// Add authentication metadata
const metadata = new GrpcMetadata();
metadata.set('cluster-id', 'cluster_abc123');
metadata.set('cluster-token', 'secret_token');

// Open stream
const stream = client.OpenStream(metadata);

// Send init request
const initMsg: ClientMessage = {
  initRequest: {
    identity: {
      clusterId: 'cluster_abc123',
      clusterName: 'production',
      namespace: 'consonant-system',
      region: 'us-east-1',
      environment: 'production'
    },
    metadata: {
      kubernetesVersion: '1.32.0',
      relayerVersion: '0.1.0',
      cloudProvider: 'aws',
      nodeCount: 3,
      labels: {}
    },
    initiatedAt: new Date(),
    capabilities: ['commands', 'events', 'telemetry']
  }
};

stream.write(initMsg);

// Handle server messages
stream.on('data', (message: ServerMessage) => {
  if (message.command) {
    // Execute command
  }
});

Protocol

Authentication

Authentication is via gRPC metadata:

metadata.set('cluster-id', 'cluster_xxx');
metadata.set('cluster-token', 'secret_token');

Message Flow

1. Relayer → Backend: StreamInitRequest
2. Backend → Relayer: StreamInitResponse
3. Bidirectional communication:
   • Backend → Relayer: Command, Heartbeat
   • Relayer → Backend: Event, CommandResult, Heartbeat

Keepalive

Both sides send Heartbeat messages every 30 seconds.

Development

Prerequisites

• Node.js ≥ 20.0.0
• protoc ≥ 3.0.0

Generate Code

npm run generate

Build

npm run build

Publish

npm run publish:alpha  # For alpha releases
npm run publish:latest # For stable releases

License

Apache-2.0