@galaxy-stack/orbit-microservices

@galaxy-stack/orbit-microservices

Part of the Orbit framework — a NestJS-style backend framework for Bun.

Installation

bun add @galaxy-stack/orbit-microservices

@galaxy-stack/orbit-microservices

Mô tả

Base abstractions và transport registry cho Orbit microservices architecture.

Cài đặt

bun add @galaxy-stack/orbit-microservices

Transports có sẵn

Package	Transport	Status	Mô tả
@galaxy-stack/orbit-microservices-tcp	TCP	✅ Full	Length-prefixed binary protocol với Bun native TCP
@galaxy-stack/orbit-microservices-redis	Redis	✅ Full	Complete RESP protocol, Pub/Sub, reconnection
@galaxy-stack/orbit-microservices-nats	NATS	✅ Full	Complete text protocol, queue groups, wildcards
@galaxy-stack/orbit-microservices-rmq	RabbitMQ	✅ Full	Complete AMQP 0-9-1, channels, ACK/NACK, reconnection
@galaxy-stack/orbit-microservices-kafka	Kafka	✅ Full	Complete binary protocol, consumer groups, partitions
@galaxy-stack/orbit-microservices-grpc	gRPC	✅ Full	Complete HTTP/2 via node:http2, gRPC framing, status codes

Note: Tất cả transports đều là full native implementation không phụ thuộc external libraries như ioredis, nats.js, amqplib, kafkajs, hay @grpc/grpc-js. TCP/Redis/NATS/RMQ/Kafka sử dụng Bun native TCP, gRPC sử dụng node:http2 module.

Decorators

Message Patterns

import { MessagePattern, EventPattern, Payload, Ctx } from '@galaxy-stack/orbit-microservices';

@Controller()
class MathController {
  @MessagePattern('sum')
  sum(@Payload() data: { a: number; b: number }): number {
    return data.a + data.b;
  }

  @EventPattern('user.created')
  handleUserCreated(@Payload() data: any, @Ctx() context: any): void {
    console.log('User created:', data);
  }
}

gRPC Methods

import { GrpcMethod, GrpcStreamMethod } from '@galaxy-stack/orbit-microservices';

@Controller()
class UserController {
  @GrpcMethod('UserService', 'GetUser')
  getUser(data: GetUserRequest): User {
    return { id: data.id, name: 'John' };
  }
}

Client Injection

import { Client, ClientProxy, Transport } from '@galaxy-stack/orbit-microservices';

class OrderService {
  @Client({ transport: 'TCP', options: { port: 3001 } })
  private client: ClientProxy;

  async getUser(id: number) {
    return this.client.send('getUser', { id });
  }
}

Server Classes

Base Server

export abstract class Server {
  protected messageHandlers: Map<string, Function>;
  protected eventHandlers: Map<string, Function>;
  
  abstract listen(callback?: () => void): Promise<void>;
  abstract close(): Promise<void>;
  
  addHandler(pattern: string, handler: Function): void;
  addEventHandler(pattern: string, handler: Function): void;
}

Client Classes

ClientProxy

export abstract class ClientProxy {
  abstract connect(): Promise<void>;
  abstract close(): Promise<void>;
  
  send<T>(pattern: string, data: any): Promise<T>;
  emit(pattern: string, data: any): void;
}

Module Integration

ClientsModule

import { MicroservicesModule } from '@galaxy-stack/orbit-microservices';
import '@galaxy-stack/orbit-microservices-tcp';

@Module({
  imports: [
    MicroservicesModule.register({
      name: 'MATH_SERVICE',
      transport: 'TCP',
      options: {
        host: 'localhost',
        port: 3001,
      },
    }),
  ],
})
class AppModule {}

Async Configuration

MicroservicesModule.registerAsync({
  name: 'MATH_SERVICE',
  transport: 'TCP',
  useFactory: async (configService: ConfigService) => ({
    host: configService.get('MATH_HOST'),
    port: configService.get('MATH_PORT'),
  }),
  inject: [ConfigService],
})

Transport-specific Configuration

TCP Transport

import '@galaxy-stack/orbit-microservices-tcp';

MicroservicesModule.register({
  name: 'TCP_SERVICE',
  transport: 'TCP',
  options: { host: 'localhost', port: 3001 },
})

Redis Transport

import '@galaxy-stack/orbit-microservices-redis';

MicroservicesModule.register({
  name: 'REDIS_SERVICE',
  transport: 'REDIS',
  options: { host: 'localhost', port: 6379 },
})

NATS Transport

import '@galaxy-stack/orbit-microservices-nats';

MicroservicesModule.register({
  name: 'NATS_SERVICE',
  transport: 'NATS',
  options: { 
    servers: ['nats://localhost:4222'],
    queue: 'my-queue',
  },
})

RabbitMQ Transport

import '@galaxy-stack/orbit-microservices-rmq';

MicroservicesModule.register({
  name: 'RMQ_SERVICE',
  transport: 'RMQ',
  options: { 
    urls: ['amqp://localhost:5672'],
    queue: 'my-queue',
  },
})

Kafka Transport

import '@galaxy-stack/orbit-microservices-kafka';

MicroservicesModule.register({
  name: 'KAFKA_SERVICE',
  transport: 'KAFKA',
  options: {
    brokers: ['localhost:9092'],
    groupId: 'my-group',
  },
})

gRPC Transport

import '@galaxy-stack/orbit-microservices-grpc';

MicroservicesModule.register({
  name: 'GRPC_SERVICE',
  transport: 'GRPC',
  options: {
    host: 'localhost',
    port: 50051,
    package: 'myservice',
  },
})

Request-Response Pattern

// Client
const result = await client.send('calculate', { a: 5, b: 3 });
console.log(result); // 8

// Server
@MessagePattern('calculate')
calculate(data: { a: number; b: number }) {
  return data.a + data.b;
}

Event-Based Pattern

// Client
client.emit('order.created', { orderId: 123 });

// Server
@EventPattern('order.created')
handleOrderCreated(data: { orderId: number }) {
  console.log('Order created:', data.orderId);
}

Error Handling

@MessagePattern('divide')
divide(data: { a: number; b: number }) {
  if (data.b === 0) {
    throw new Error('Division by zero');
  }
  return data.a / data.b;
}

// Client receives error
try {
  await client.send('divide', { a: 10, b: 0 });
} catch (error) {
  console.error(error.message); // 'Division by zero'
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Application                          │
├─────────────────────────────────────────────────────────┤
│  @MessagePattern  │  @EventPattern  │  @GrpcMethod     │
├─────────────────────────────────────────────────────────┤
│                 Transport Registry                      │
├───────┬───────┬───────┬───────┬───────┬────────────────┤
│  TCP  │ Redis │ NATS  │  RMQ  │ Kafka │     gRPC       │
├───────┴───────┴───────┴───────┴───────┴────────────────┤
│                   Bun Native TCP                        │
└─────────────────────────────────────────────────────────┘

Luồng hoạt động

Request-Response

Producer                           Consumer
   │                                  │
   │  ──────── Request ──────────►    │
   │           (pattern)              │
   │                                  │
   │  ◄─────── Response ──────────    │
   │         (result/error)           │

Event-Based (Fire-and-forget)

Producer                           Consumer(s)
   │                                  │
   │  ──────── Event ────────────►    │
   │           (pattern)              │
   │                                  │
   │         (no response)            │