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

Auto-Disposal Guide for Network Clients

This guide explains how to properly use auto-disposal with the createNetworkClient() function.

Overview

The NetworkClientWithAgents class implements JavaScript's explicit resource management proposal via Symbol.dispose and Symbol.asyncDispose. This provides automatic cleanup of resources when clients go out of scope.

When to Use await using

✅ Use await using for:

1. Short-lived scripts and examples that complete and exit
2. Test cases where cleanup is needed after each test
3. Client-only applications that don't serve agents or containers
4. Request-response patterns where the client is used temporarily

// Example: Simple client usage with auto-disposal
async function fetchData() {
  await using client = createNetworkClient('localhost:3737')
  await client.waitConnection(5000)

  const container = await client.get('my-service' as ContainerKind, {})
  const result = await container.request('getData')

  return result
  // Client automatically disposed here
}

❌ Do NOT use await using for:

1. Long-running services that need to stay connected
2. Applications hosting agents and containers via serveAgent()
3. Production servers that should run indefinitely
4. Background workers that process jobs continuously

// Example: Long-running service (DON'T use 'await using')
class MyService {
  private client: ReturnType<typeof createNetworkClient> | null = null

  async start() {
    // Keep strong reference - NO 'await using'
    this.client = createNetworkClient('localhost:3737')
    await this.client.waitConnection(5000)

    // Serve containers
    await this.client.serveAgent('localhost:3738', {
      'my-container': myContainerFactory
    })

    console.log('Service started - will run indefinitely')
  }

  async stop() {
    // Manual cleanup when ready
    if (this.client) {
      await this.client.close()
      this.client = null
    }
  }
}

// Usage
const service = new MyService()
await service.start()

// Graceful shutdown
process.on('SIGTERM', () => service.stop())
process.on('SIGINT', () => service.stop())

// Keep running
await new Promise(() => {})

Auto-Disposal Behavior

When you use await using, the client will be automatically disposed:

1. At the end of the block where it was declared
2. On exception/error (ensures cleanup even on failures)
3. On early return from the function

async function example() {
  await using client = createNetworkClient('localhost:3737')

  // If an error occurs here...
  throw new Error('Something went wrong')

  // ...client.close() is still called automatically
}

Manual Disposal

For long-running services, manage the lifecycle manually:

// Create without auto-disposal
const client = createNetworkClient('localhost:3737')

// Use the client...
await client.waitConnection(5000)

// Manual cleanup when done
await client.close()

Best Practices

For Examples and Demos

All example scripts should use await using for automatic cleanup:

async function main() {
  // Setup infrastructure (servers, agents)
  const server = new NetworkServer(...)
  const agent = new AgentImpl(...)

  // Client with auto-disposal
  await using client = createNetworkClient('localhost:3737')
  await client.register(agent)

  // Do work...

  // Manual cleanup of infrastructure
  await server.close()
}

For Production Services

Production services should use manual lifecycle management:

class ProductionService {
  private client: NetworkClient | null = null

  async start() {
    this.client = createNetworkClient(config.networkUrl)
    await this.client.waitConnection()
    await this.setupContainers()

    // Setup signal handlers
    process.on('SIGTERM', () => this.shutdown())
    process.on('SIGINT', () => this.shutdown())
  }

  async shutdown() {
    console.log('Graceful shutdown initiated...')
    if (this.client) {
      await this.client.close()
    }
    process.exit(0)
  }
}

Migration from Old Code

If you have existing code using manual client.close():

Before (manual cleanup):

const client = createNetworkClient('localhost:3737')
try {
  await client.waitConnection(5000)
  // ... use client ...
} finally {
  await client.close()
}

After (auto-disposal):

await using client = createNetworkClient('localhost:3737')
await client.waitConnection(5000)
// ... use client ...
// Automatically closed

Common Pitfalls

❌ Wrong: Using await using in long-running services

// BAD: Service will stop when function returns!
async function startService() {
  await using client = createNetworkClient('localhost:3737')
  await client.serveAgent('localhost:3738', factories)
  // Client disposed when function returns - service stops!
}

✅ Correct: Keep reference for long-running services

// GOOD: Service keeps running
let client: NetworkClient | null = null

async function startService() {
  client = createNetworkClient('localhost:3737')
  await client.serveAgent('localhost:3738', factories)
  // Service continues running
}

async function stopService() {
  if (client) {
    await client.close()
    client = null
  }
}

Summary

• Short-lived operations: Use await using for automatic cleanup
• Long-running services: Use regular assignment and manual cleanup
• Hosting agents/containers: Always use manual lifecycle management
• Examples and tests: Prefer await using for cleaner code

The auto-disposal feature makes resource management simpler and safer for temporary client usage while still allowing full control for production services.