huly-platform/foundations/net/docs/QUICKSTART.md

Quick Start Guide

Get started with Huly Virtual Network in under 10 minutes!

⚠️ Important Limitations

Network Service Constraints:

The Network Server (central coordinator) must run as a single instance only:

• ❌ Does NOT support high availability or clustering
• ❌ Cannot run multiple network servers simultaneously
• ✅ Agents and containers DO support HA through stateless registration

For production, use process monitoring (systemd, PM2, Kubernetes) to ensure quick restarts. Agents automatically reconnect when the network service restarts.

Prerequisites

• Node.js: 22.0.0 or higher
• PNPM: 10.15 or higher (automatically installed via Rush)
• ZeroMQ: Native dependencies (automatically installed)
• Operating System: Linux, macOS, or Windows

Installation

Option 1: Clone and Build (Recommended for Development)

# Clone the repository
git clone https://github.com/hcengineering/huly.net.git
cd huly.net

# Install dependencies
node common/scripts/install-run-rush.js install

# Build all packages
node common/scripts/install-run-rush.js build

# Run tests to verify
node common/scripts/install-run-rush.js test

Option 2: Docker (Recommended for Production)

# Pull the network server image
docker pull hardcoreeng/network-pod:latest

# Run the network server
docker run -d \
  --name huly-network \
  -p 3737:3737 \
  hardcoreeng/network-pod:latest

Option 3: NPM Packages (Coming Soon)

npm install @hcengineering/network-core \
            @hcengineering/network-client \
            @hcengineering/network-server

Your First Network Application

Step 1: Create a Container

Create a file my-container.ts:

import type { Container, ContainerUuid, ClientUuid } from '@hcengineering/network-core'

export class HelloWorldContainer implements Container {
  constructor(readonly uuid: ContainerUuid) {
    console.log(`Container ${uuid} created`)
  }

  async request(operation: string, data?: any): Promise<any> {
    switch (operation) {
      case 'greet':
        return { message: `Hello, ${data?.name || 'World'}!` }
      case 'status':
        return { status: 'running', uuid: this.uuid }
      default:
        return { error: 'Unknown operation' }
    }
  }

  async ping(): Promise<void> {
    // Health check
  }

  async terminate(): Promise<void> {
    console.log(`Container ${this.uuid} terminated`)
  }

  connect(clientId: ClientUuid, broadcast: (data: any) => Promise<void>): void {}
  disconnect(clientId: ClientUuid): void {}
}

Step 2: Start the Network Server

Create a file server.ts:

import { NetworkImpl, TickManagerImpl } from '@hcengineering/network-core'
import { NetworkServer } from '@hcengineering/network-server'

const tickManager = new TickManagerImpl(1000)
tickManager.start()

const network = new NetworkImpl(tickManager)
const server = new NetworkServer(network, tickManager, '*', 3737)

console.log('🚀 Network server started on port 3737')

// Graceful shutdown
process.on('SIGINT', async () => {
  console.log('\nShutting down...')
  await server.close()
  tickManager.stop()
  process.exit(0)
})

Step 3: Create an Agent

Create a file agent.ts:

import { createNetworkClient } from '@hcengineering/network-client'
import { HelloWorldContainer } from './my-container'
import type { GetOptions, ContainerUuid } from '@hcengineering/network-core'

// Create client and serve agent with container factory
const client = createNetworkClient('localhost:3737')
await client.waitConnection(5000)

await client.serveAgent('localhost:3738', {
  'hello-world': async (options: GetOptions) => {
    const uuid = options.uuid ?? (`hello-${Date.now()}` as ContainerUuid)
    const container = new HelloWorldContainer(uuid)
    return {
      uuid,
      container,
      endpoint: `hello://localhost/${uuid}` as any
    }
  }
})

console.log('🤖 Agent server started on port 3738')

// Graceful shutdown
process.on('SIGINT', async () => {
  console.log('\nShutting down agent...')
  await client.close()
  process.exit(0)
})

Step 4: Create a Client

Create a file client.ts:

import { createNetworkClient } from '@hcengineering/network-client'

async function main() {
  // Connect to network
  const client = createNetworkClient('localhost:3737')
  await client.waitConnection(5000)
  console.log('✅ Connected to network')

  // Register the agent (if running separately, do this in agent.ts)
  // await client.register(agent)

  // Get a container
  const containerRef = await client.get('hello-world' as any, {})
  console.log(`📦 Got container: ${containerRef.uuid}`)

  // Send requests
  const greeting = await containerRef.request('greet', { name: 'Alice' })
  console.log('Response:', greeting)

  const status = await containerRef.request('status')
  console.log('Status:', status)

  // Cleanup
  await containerRef.close()
  await client.close()
  console.log('👋 Disconnected')
}

main().catch(console.error)

Step 5: Run Everything

Open three terminals:

Terminal 1: Start Network Server

npx ts-node server.ts

Terminal 2: Start Agent

npx ts-node agent.ts

Terminal 3: Run Client

npx ts-node client.ts

You should see:

✅ Connected to network
📦 Got container: hello-1234567890
Response: { message: 'Hello, Alice!' }
Status: { status: 'running', uuid: 'hello-1234567890' }
👋 Disconnected

All-in-One Example

For a single-file demo, create demo.ts:

import { NetworkImpl, TickManagerImpl } from '@hcengineering/network-core'
import { NetworkServer } from '@hcengineering/network-server'
import { createNetworkClient } from '@hcengineering/network-client'
import type { Container, ContainerUuid, ClientUuid, GetOptions } from '@hcengineering/network-core'

class DemoContainer implements Container {
  constructor(readonly uuid: ContainerUuid) {}

  async request(op: string, data?: any): Promise<any> {
    return { message: `Processed ${op}`, data }
  }

  async ping(): Promise<void> {}
  async terminate(): Promise<void> {}
  connect(clientId: ClientUuid, broadcast: (data: any) => Promise<void>): void {}
  disconnect(clientId: ClientUuid): void {}
}

async function demo() {
  // 1. Start network (NOTE: Only one instance allowed - no HA support)
  const tickManager = new TickManagerImpl(1)
  tickManager.start()
  const network = new NetworkImpl(tickManager)
  const server = new NetworkServer(network, tickManager, '*', 3737)
  console.log('✅ Network started')

  // 2. Connect client and serve agent
  const client = createNetworkClient('localhost:3737')
  await client.waitConnection(5000)

  await client.serveAgent('localhost:3738', {
    demo: async (options: GetOptions) => {
      const uuid = options.uuid ?? (`demo-${Date.now()}` as ContainerUuid)
      return {
        uuid,
        container: new DemoContainer(uuid),
        endpoint: `demo://localhost/${uuid}` as any
      }
    }
  })
  console.log('✅ Agent started')
  console.log('✅ Client connected')

  // 3. Use container
  const ref = await client.get('demo' as any, {})
  const result = await ref.request('test', { value: 42 })
  console.log('✅ Result:', result)

  // 5. Cleanup
  await ref.close()
  await client.close()
  await agentServer.close()
  await server.close()
  tickManager.stop()
  console.log('✅ Demo complete!')
}

demo().catch(console.error)

Run it:

npx ts-node demo.ts

Next Steps

Now that you have a working setup:

1. Learn Core Concepts: Read Core Concepts to understand the architecture
2. Build Containers: Explore Container Development Guide
3. Try Examples: Run examples from the examples/ directory
4. Add Features: Implement event broadcasting, multi-tenancy, or HA
5. Deploy: Follow Production Deployment Guide

Quick References

Container Interface

interface Container {
  request(operation: string, data?: any, clientId?: ClientUuid): Promise<any>
  ping(): Promise<void>
  terminate(): Promise<void>
  connect(clientId: ClientUuid, broadcast: (data: any) => Promise<void>): void
  disconnect(clientId: ClientUuid): void
  onTerminated?(): void
}

Common Operations

Get a container:

const ref = await client.get('kind' as ContainerKind, {
  uuid: 'optional-uuid',
  labels: ['tag1', 'tag2']
})

Send a request:

const result = await ref.request('operation', { data: 'value' })

Connect for events:

const connection = await ref.connect()
connection.on = async (event) => {
  console.log('Event:', event)
}

Cleanup:

await connection.close()
await ref.close()
await client.close()

Troubleshooting

Can't connect to network:

• Ensure the network server is running
• Check the port (default: 3737)
• Verify firewall settings

Container not found:

• Register the agent before requesting containers
• Check that the agent supports that container kind
• Ensure the agent is still alive

Timeout errors:

• Increase timeout: createNetworkClient('host:port', 3600)
• Check network latency
• Verify services are responding

For more help, see the Troubleshooting Guide.

Resources

• Examples Directory - Complete working examples
• Core Concepts - Architecture deep dive
• API Reference - Detailed API documentation
• GitHub Repository

---

Ready to build something amazing? Start with the Container Development Guide! 🚀