38 remote access foundation

[lxsaah]

Added

Remote Access Foundation (AimX v1 Protocol)

Complete implementation of Unix domain socket-based remote access protocol for introspection and control of AimDB instances.

Core Remote Access Module (aimdb-core/src/remote/)

• Protocol specification and implementation (AimX v1)
• NDJSON-based request/response format with streaming support
• Configuration system (AimxConfig) with security policies
• Connection supervisor (RemoteSupervisor) for managing client lifecycle
• Per-connection handler (ConnectionHandler) for protocol execution
• Metadata tracking system for record introspection
• Comprehensive error codes and error handling

Protocol Methods Implemented

• Handshake: Hello → Welcome with version negotiation and capability exchange
• record.list: List all registered records with full metadata (type, buffer config, producer/consumer counts, timestamps)
• record.get: Retrieve current value of any record with JSON serialization
• record.set: Update record values remotely (with safety checks - only records without producers can be modified)
• record.subscribe: Real-time streaming of record updates via event messages
• record.unsubscribe: Stop streaming for active subscriptions

Security & Safety

• Configurable security policies: ReadOnly, ReadWrite, custom per-record permissions
• Write protection: Records with active producers cannot be overridden remotely
• Per-record write allowlists for fine-grained control
• Connection limits and subscription queue size configuration
• Auth token support (prepared for future authentication)

Type System Extensions

• TypedRecordStorage trait for serialization support
• get_typed_record<T>() helper for type-safe record lookups by TypeId
• set_record_from_json() for remote updates with validation
• last_value_json() and last_produced_json() for serialized access
• Buffer trait extensions for serialization capabilities

Examples & Documentation

• examples/remote-access-demo/ - Complete server/client demonstration
  • Server with 5 different record types (Temperature, SystemStatus, UserEvent, Config, AppSettings)
  • Client showcasing all protocol methods (list, get, set, subscribe, unsubscribe)
  • Live data simulation (temperature updates every 2s, system status every 5s)
  • Safety demonstrations (write protection, producer conflicts)
• Design document docs/design/008-M3-remote-access.md with full specification
  • Protocol format and message schemas
  • Security model and permission system
  • Implementation checklist and testing guidelines

Builder Integration

• AimDbBuilder::with_remote_access() for easy configuration
• Automatic supervisor task spawning on build
• Seamless integration with existing Tokio adapter

Dependencies

• serde and serde_json for serialization (optional serde feature)
• Unix domain socket support via std::os::unix::net

Changed

• Extended DbError with SerializationError, RemoteAccessError, and NotFound variants
• AimDbBuilder now supports remote access configuration
• Record registration macros enhanced to support serialization traits
• Buffer traits extended with JSON serialization capabilities
• Updated Embassy submodule reference

[Copilot]

Pull Request Overview

This PR implements the AimX v1 remote access protocol, enabling introspection and control of AimDB instances over Unix domain sockets using NDJSON. The implementation adds read/write capabilities with fine-grained security controls, real-time subscription streaming, and comprehensive metadata tracking.

Key Changes:

• Complete AimX v1 protocol implementation with five methods: record.list, record.get, record.set, record.subscribe, record.unsubscribe
• Security model with read-only default, optional write permissions, and producer protection rules
• Event funnel architecture for clean subscription management and NDJSON streaming

Reviewed Changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/design/008-M3-remote-access.md	Complete AimX v1 protocol specification with security model and implementation architecture
aimdb-core/src/remote/	Core remote access module with protocol, config, metadata, supervisor, and handler implementations
aimdb-core/src/typed_record.rs	Extended with JSON serialization, RecordValue wrapper, metadata tracking, and latest() API
aimdb-core/src/builder.rs	Added remote access configuration, list_records(), set_record_from_json(), and subscribe_record_updates()
examples/remote-access-demo/	Complete client/server demonstration with 5 record types and all protocol methods
aimdb-core/Cargo.toml	Added tokio dependency for Unix socket support