94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
# packages/client/
|
|
|
|
Core IPC client library for OpenPets desktop app communication.
|
|
|
|
## Responsibility
|
|
|
|
Provides the foundational client library for all OpenPets integrations. Handles discovery file reading, TCP socket connections (including WSL cross-platform), request/response protocol, and high-level pet operations (status, list, install, lease, react, say).
|
|
|
|
## Design/Patterns
|
|
|
|
**Protocol Layer** (`protocol.ts`):
|
|
- Defines IPC protocol version (v1), message limits (16KB), timeouts (2s connect, 3s response)
|
|
- Request/response types with discriminated union (`ok: true/false`)
|
|
- Reaction validation against allowed enum values
|
|
- Custom `OpenPetsClientError` with error codes
|
|
|
|
**Discovery Layer** (`discovery.ts`):
|
|
- Cross-platform discovery file path resolution (macOS, Windows, Linux/XDG)
|
|
- File validation (size, permissions, symlink checks)
|
|
- Endpoint validation: Unix sockets, Windows named pipes, TCP (IPv4)
|
|
- TCP/WSL cross-platform support: Windows desktop → WSL client via private IPs
|
|
- Security: XDG_RUNTIME_DIR permission checks (0o700, ownership)
|
|
|
|
**TCP Endpoint Security:**
|
|
- IPv4 only (no hostnames)
|
|
- Private/local addresses only:
|
|
- Loopback: 127.0.0.0/8
|
|
- Private: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
|
|
- Link-local: 169.254.0.0/16
|
|
- Rejects 0.0.0.0, public IPs, hostnames
|
|
- Enables WSL clients to connect to Windows desktop app
|
|
|
|
**Client Layer** (`index.ts`):
|
|
- Factory pattern: `createOpenPetsClient(options)` returns `OpenPetsClient` interface
|
|
- Methods: `hello()`, `status()`, `listPets()`, `installPet()`, `acquireLease()`, `heartbeatLease()`, `releaseLease()`, `react()`, `say()`
|
|
- Lease-aware operations for multi-pet targeting
|
|
- Result parsers with validation
|
|
|
|
**Socket Management**:
|
|
- Node.js `net.createConnection()` for TCP/Unix sockets/Windows named pipes
|
|
- Dual timeout handling (connect + response)
|
|
- Line-delimited JSON protocol (`\n` separator)
|
|
- Buffer size enforcement (16KB max)
|
|
|
|
## Flow
|
|
|
|
```
|
|
Client Method Call
|
|
↓
|
|
readDiscoveryFile() → Parse ipc.json (token, endpoint)
|
|
↓
|
|
sendRequest() → Build request (id, version, token, method, params)
|
|
↓
|
|
net.createConnection(endpoint) → Write JSON + newline
|
|
↓
|
|
Wait for response (buffer until newline)
|
|
↓
|
|
parseIpcResponse() → Validate shape, return result or throw
|
|
```
|
|
|
|
TCP/WSL Cross-Platform Flow:
|
|
```
|
|
WSL Client → readDiscoveryFile()
|
|
↓
|
|
Endpoint: tcp://192.168.x.x:port (Windows host IP)
|
|
↓
|
|
validateDiscovery() → allowsCrossPlatformDiscovery()
|
|
↓
|
|
net.createConnection({ host, port }) → Windows desktop app
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
**Consumers** (all depend on this package):
|
|
- `@open-pets/cli` - CLI commands
|
|
- `@open-pets/mcp` - MCP tool implementations
|
|
- `@open-pets/claude` - Hook execution
|
|
- `@open-pets/opencode` - Plugin runtime
|
|
- `@open-pets/install-pet` - Direct installation fallback
|
|
|
|
**Desktop App**: Communicates with OpenPets desktop app via:
|
|
- Unix domain socket (macOS/Linux)
|
|
- Windows named pipe (Windows)
|
|
- TCP socket (WSL cross-platform)
|
|
|
|
**Exports**:
|
|
- `createOpenPetsClient()` - Main factory
|
|
- `sendRequest()` - Low-level request function
|
|
- `readDiscoveryFile()`, `getDiscoveryFilePath()` - Discovery utilities
|
|
- `parseIpcEndpoint()`, `validateEndpoint()` - Endpoint handling
|
|
- `OpenPetsClientError`, error codes, types
|
|
|
|
**Contracts**:
|
|
- `contracts/client-protocol.contract.ts` - Runtime protocol validation tests
|