Skip to content

codemap.md

Latest commit

 

History

History
96 lines (72 loc) · 3.53 KB

codemap.md

File metadata and controls

96 lines (72 loc) · 3.53 KB
Raw

packages/client/src/

Core IPC client implementation for OpenPets desktop app communication.

Files

index.ts

Main client implementation (193 lines). createOpenPetsClient() factory, all client methods, result parsers, and sendRequest() for low-level IPC.

Client Methods:

  • hello() - Protocol handshake
  • status(options?) - App connectivity check with graceful error handling
  • listPets() - Fetch installed pets with metadata
  • installPet(petId) - Install pet with 60s timeout
  • acquireLease(options?) - Get lease for targeted pet operations
  • heartbeatLease(leaseId) - Keep lease alive
  • releaseLease(leaseId) - Release acquired lease
  • react(reaction, options?) - Send reaction (lease-aware)
  • say(message, options?) - Display message (lease-aware, optional reaction)

Result Parsers:

  • parsePetListResult() - Validates pet list response
  • parsePetInstallResult() - Validates install response
  • validatePetId() - Pet ID format validation (regex: ^[a-z0-9][a-z0-9_-]{0,63}$)

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)

protocol.ts

IPC protocol constants, request/response types, parseIpcResponse(), validateReaction(), OpenPetsClientError class.

Protocol Constants:

  • Version: v1
  • Message limit: 16KB
  • Timeouts: 2s connect, 3s response

Error Codes:

  • unavailable - Desktop app not reachable
  • invalid_discovery - Discovery file malformed
  • invalid_token - Authentication failed
  • invalid_response - Response parsing failed
  • connect_timeout, response_timeout - Timeout errors
  • request_too_large, response_too_large - Size limits

Validation:

  • validateReaction() - Ensures reaction is in allowed enum
  • parseIpcResponse() - Discriminated union parsing (ok: true/false)

discovery.ts

Discovery file handling (226 lines). getDiscoveryFilePath(), readDiscoveryFile(), validateDiscovery(), validateEndpoint(), platform-specific path logic, XDG security checks.

Platform Paths:

  • macOS: ~/Library/Application Support/OpenPets/runtime/ipc.json
  • Windows: %APPDATA%/OpenPets/runtime/ipc.json
  • Linux: $XDG_RUNTIME_DIR/openpets/ipc.json (preferred) or ~/.config/OpenPets/runtime/ipc.json

Endpoint Types:

  • Unix sockets: /tmp/openpets-*/openpets-*.sock or $XDG_RUNTIME_DIR/openpets/*.sock
  • Windows named pipes: \\.\pipe\openpets-*
  • TCP: tcp://<host>:<port> (IPv4 only, private/local addresses)

TCP/WSL Support:

  • Cross-platform discovery for Windows desktop → WSL client
  • Validates private/local IPv4: loopback (127.x), private (10.x, 172.16-31.x, 192.168.x), link-local (169.254.x)
  • Rejects hostnames, 0.0.0.0, public IPs

Security:

  • XDG_RUNTIME_DIR permission checks (0o700, ownership)
  • File size limits (16KB)
  • Symlink rejection
  • Platform mismatch detection

smoke.ts

Manual testing CLI for client operations (hello, status, react, say, invalid-token).

Related Contracts

../contracts/client-protocol.contract.ts

Contract validation (moved from src/check-client-protocol.ts). Runtime assertions for protocol compliance.

Test Coverage:

  • Discovery validation (protocol, version, endpoint, token)
  • Endpoint parsing (Unix socket, Windows pipe, TCP)
  • TCP private IP validation (loopback, private ranges, link-local)
  • Cross-platform discovery (Windows desktop → WSL)
  • Public IP rejection
  • Response parsing (ok/error cases)
  • Pet list/install result parsing