@bobfrankston/msgapidefs 0.1.23 → 0.1.25

package/UDP-PLAN.md

@@ -0,0 +1,499 @@
+# UDP Support Plan for msgapi
+
+## Overview
+
+Add UDP networking capabilities to msgapi, enabling lightweight, connectionless communication for:
+- Local device control and discovery
+- IoT messaging
+- Low-latency event broadcasting
+- Inter-process communication
+- Home automation integration
+
+**Target Use Case**: Trusted, friendly applications controlled by the user. This is for power users running their own apps, not for sandboxed web content.
+
+**Reference Implementation**: `y:\dev\homecontrol\utils\netsupport`
+
+---
+
+## API Design
+
+### msgapi.udp Object
+
+```typescript
+interface UdpSocket {
+    /** Local port this socket is bound to */
+    readonly port: number;
+    
+    /** Local address this socket is bound to */
+    readonly address: string;
+    
+    /** Send a UDP message */
+    send(message: string | Uint8Array, port: number, address?: string): Promise<void>;
+    
+    /** Register a message handler (non-exclusive, multiple handlers allowed) */
+    onMessage(handler: (message: UdpMessage) => void): void;
+    
+    /** Remove a message handler */
+    offMessage(handler: (message: UdpMessage) => void): void;
+    
+    /** Close the socket */
+    close(): Promise<void>;
+}
+
+interface UdpMessage {
+    /** Message content as string */
+    data: string;
+    
+    /** Raw message content as Uint8Array */
+    buffer: Uint8Array;
+    
+    /** Sender's address */
+    remoteAddress: string;
+    
+    /** Sender's port */
+    remotePort: number;
+    
+    /** Size of message in bytes */
+    size: number;
+}
+
+interface UdpOptions {
+    /** Port to bind to (0 = random available port) */
+    port?: number;
+    
+    /** Address to bind to (default: '0.0.0.0' for all interfaces) */
+    address?: string;
+    
+    /** Enable SO_REUSEADDR (allows multiple sockets on same port) */
+    reuseAddress?: boolean;
+    
+    /** Enable SO_BROADCAST for broadcast messages */
+    broadcast?: boolean;
+    
+    /** Join multicast group(s) */
+    multicast?: string | string[];
+}
+
+interface MsgAPI {
+    // ... existing properties ...
+    
+    /**
+     * UDP networking operations namespace
+     * Requires -allowUdp flag when launching msgview/msger
+     */
+    udp?: {
+        /**
+         * Create a UDP socket
+         * @param options - Socket configuration options
+         * @returns UDP socket instance
+         * @example
+         * // Simple receiver on port 8080
+         * const socket = await msgapi.udp.create({ port: 8080 });
+         * socket.onMessage(msg => {
+         *     console.log(`Received from ${msg.remoteAddress}:${msg.remotePort}: ${msg.data}`);
+         * });
+         * 
+         * @example
+         * // Broadcast sender with reuse address
+         * const socket = await msgapi.udp.create({ 
+         *     port: 0,  // Random port
+         *     broadcast: true,
+         *     reuseAddress: true 
+         * });
+         * await socket.send('Hello Network!', 8080, '255.255.255.255');
+         */
+        create(options?: UdpOptions): Promise<UdpSocket>;
+        
+        /**
+         * Create a multicast receiver
+         * Convenience method for multicast scenarios
+         * @param multicastGroup - Multicast group address (e.g., '239.255.255.250')
+         * @param port - Port to listen on
+         * @returns UDP socket joined to multicast group
+         * @example
+         * const socket = await msgapi.udp.createMulticast('239.255.0.1', 5353);
+         * socket.onMessage(msg => console.log('Multicast:', msg.data));
+         */
+        createMulticast(multicastGroup: string, port: number): Promise<UdpSocket>;
+        
+        /**
+         * Send a one-off UDP message without creating a persistent socket
+         * @param message - Message to send
+         * @param port - Destination port
+         * @param address - Destination address (default: 'localhost')
+         * @example
+         * await msgapi.udp.send('Quick message', 8080, '192.168.1.100');
+         */
+        send(message: string | Uint8Array, port: number, address?: string): Promise<void>;
+    };
+}
+```
+
+---
+
+## Implementation Requirements
+
+### Permission/Security Model
+
+UDP requires explicit permission, similar to `allowFs`:
+
+**Command-line flag:**
+- **msgview**: `-allowUdp` 
+- **msger**: `-allowUdp`
+
+**Config file (recommended for friendly apps):**
+```json
+{
+    "url": "http://localhost:8080/myapp",
+    "flags": {
+        "allowFs": true,
+        "allowUdp": true
+    }
+}
+```
+
+**Rationale**: This is for trusted applications the user controls. Like `allowFs`, `allowUdp` gives power to friendly apps that need it. The user explicitly enables it in their config file.
+
+**Philosophy**: We're not sandboxing untrusted web content - we're empowering user-controlled applications with full system capabilities when requested.
+
+### Non-Exclusive Listening
+
+Multiple handlers can listen to the same port:
+- `reuseAddress: true` enables SO_REUSEADDR socket option
+- Multiple `onMessage()` handlers can be registered on same socket
+- Useful for multiple windows/instances receiving same broadcasts
+
+### Platform-Specific Notes
+
+#### Node.js/msgview (Electron)
+- Use Node.js `dgram` module
+- Full UDP support including multicast
+- Works on Windows, Linux, macOS
+
+#### Rust/msger (wry)
+- Use Rust `tokio::net::UdpSocket`
+- Full platform support
+- Async message handling via Tokio runtime
+
+#### C#/msga (.NET MAUI)
+- Use `System.Net.Sockets.UdpClient`
+- Platform: Windows, Android (iOS restrictions may apply)
+- iOS: UDP requires special entitlements, may be restricted
+
+---
+
+## Usage Examples
+
+### Example 1: Simple Sender/Receiver
+
+**Sender:**
+```javascript
+const socket = await msgapi.udp.create({ port: 0 });  // Random port
+await socket.send('Hello!', 8080, '192.168.1.100');
+await socket.close();
+```
+
+**Receiver:**
+```javascript
+const socket = await msgapi.udp.create({ 
+    port: 8080,
+    reuseAddress: true  // Allow multiple receivers
+});
+
+socket.onMessage(msg => {
+    console.log(`From ${msg.remoteAddress}: ${msg.data}`);
+    // Echo back
+    socket.send(`Echo: ${msg.data}`, msg.remotePort, msg.remoteAddress);
+});
+```
+
+### Example 2: Broadcast Discovery
+
+**Service Announcer:**
+```javascript
+const socket = await msgapi.udp.create({ 
+    broadcast: true 
+});
+
+setInterval(async () => {
+    await socket.send(
+        JSON.stringify({ service: 'MyApp', port: 9000 }),
+        8888,
+        '255.255.255.255'
+    );
+}, 5000);
+```
+
+**Service Discovery:**
+```javascript
+const socket = await msgapi.udp.create({ 
+    port: 8888,
+    reuseAddress: true 
+});
+
+socket.onMessage(msg => {
+    const service = JSON.parse(msg.data);
+    console.log(`Found: ${service.service} at ${msg.remoteAddress}:${service.port}`);
+});
+```
+
+### Example 3: Multicast Communication
+
+**Multicast Sender:**
+```javascript
+const socket = await msgapi.udp.create({ broadcast: true });
+await socket.send('Event occurred!', 5353, '239.255.0.1');
+```
+
+**Multicast Receiver:**
+```javascript
+const socket = await msgapi.udp.createMulticast('239.255.0.1', 5353);
+socket.onMessage(msg => {
+    console.log('Multicast event:', msg.data);
+});
+```
+
+### Example 4: Home Automation Control
+
+```javascript
+// Config file enables UDP:
+// { "flags": { "allowUdp": true }, ... }
+
+// Listen for button press events
+const listener = await msgapi.udp.create({ 
+    port: 7777,
+    reuseAddress: true 
+});
+
+listener.onMessage(async msg => {
+    const event = JSON.parse(msg.data);
+    
+    if (event.type === 'button_press') {
+        console.log(`Button ${event.button} pressed`);
+        
+        // Send command to light controller
+        const controller = await msgapi.udp.create();
+        await controller.send(
+            JSON.stringify({ command: 'toggle', device: 'light1' }),
+            8888,
+            'light-controller.local'  // DNS resolution supported
+        );
+        await controller.close();
+    }
+});
+```
+
+### Example 5: Multiple Listeners (Non-Exclusive)
+
+```javascript
+// Window 1: Logger
+const socket1 = await msgapi.udp.create({ 
+    port: 9000, 
+    reuseAddress: true 
+});
+socket1.onMessage(msg => console.log('[LOG]', msg.data));
+
+// Window 2: Processor
+const socket2 = await msgapi.udp.create({ 
+    port: 9000, 
+    reuseAddress: true 
+});
+socket2.onMessage(msg => processMessage(msg.data));
+
+// Both receive the same messages!
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Core Implementation
+
+#### msgapidefs (TypeScript definitions)
+- [ ] Add `UdpSocket` interface
+- [ ] Add `UdpMessage` interface
+- [ ] Add `UdpOptions` interface
+- [ ] Add `msgapi.udp` namespace to `MsgAPI` interface
+- [ ] Update README.md with UDP examples
+- [ ] Add to msgapi-plan.md status table
+
+#### msgview (Electron/Node.js)
+- [ ] Implement `dgram`-based UDP socket wrapper
+- [ ] Add `-allowUdp` flag to CLI parser
+- [ ] Wire up IPC handlers for UDP operations
+- [ ] Handle socket cleanup on window close
+- [ ] Implement message handler registration/removal
+- [ ] Add error handling for network errors
+- [ ] Test on Windows, Linux, macOS
+
+#### msger (Rust/wry)
+- [ ] Add `tokio::net::UdpSocket` wrapper
+- [ ] Add `--allow-udp` CLI flag
+- [ ] Implement message handler callback system
+- [ ] Handle async message reception in Tokio runtime
+- [ ] Wire up webview invoke handlers
+- [ ] Implement socket cleanup on window close
+- [ ] Test on Windows (primary target)
+
+#### msga (C#/.NET MAUI)
+- [ ] Implement `UdpClient` wrapper in Services/
+- [ ] Add allowUdp config option
+- [ ] Wire up JavaScript-to-C# bridge for UDP
+- [ ] Handle message callbacks via WebView
+- [ ] Test on Windows, Android
+- [ ] Document iOS limitations
+
+### Phase 2: Advanced Features
+- [ ] Multicast support testing
+- [ ] Broadcast support testing
+- [ ] IPv6 support
+- [ ] Socket options (TTL, buffer sizes)
+- [ ] Rate limiting/throttling options
+- [ ] Connection statistics/monitoring
+
+### Phase 3: Documentation & Examples
+- [ ] Add UDP section to main README
+- [ ] Create UDP examples repository
+- [ ] Document common patterns (discovery, control, etc.)
+- [ ] Add troubleshooting guide
+- [ ] Document firewall configuration needs
+
+---
+
+## Security Considerations
+
+### Trust Model
+
+**This is for friendly applications, not adversarial content.**
+
+The user:
+- Writes or controls the HTML/JS being loaded
+- Explicitly enables `allowUdp` in their config file
+- Understands they're giving the app network access
+- Similar trust level to `allowFs` (full file system access)
+
+### Design Principles
+1. **Explicit opt-in**: Require `allowUdp` in config or CLI flag
+2. **Full power when enabled**: No artificial restrictions for trusted apps
+3. **Clear documentation**: User understands what they're enabling
+4. **Useful error messages**: If UDP fails, explain clearly why
+
+### Reasonable Safeguards
+1. **Message size limits**: Respect UDP's 64KB datagram limit (natural constraint)
+2. **Socket cleanup**: Auto-close sockets when window closes (resource management)
+3. **Error handling**: Clear errors for invalid addresses/ports
+
+### NOT Implemented (Trust-Based)
+- ❌ Rate limiting (user's app, user's choice)
+- ❌ IP restrictions (user may need any destination)
+- ❌ Port restrictions (user may need privileged ports with sudo)
+- ❌ DNS blocking (user should be able to resolve hostnames)
+- ❌ Audit logging (adds overhead, user controls the app)
+
+**Rationale**: If we trust the user with `allowFs` (full filesystem), we can trust them with UDP. Both are powerful, both require explicit enablement.
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- Socket creation with various options
+- Message sending/receiving
+- Handler registration/removal
+- Socket cleanup
+- Error conditions
+
+### Integration Tests
+- msgview ↔ msgview communication
+- msger ↔ msger communication
+- Cross-implementation (msgview ↔ msger)
+- Broadcast reception by multiple instances
+- Multicast group joining
+
+### Platform Tests
+- Windows (primary target)
+- Linux (msgview, msger)
+- macOS (msgview)
+- Android (msga)
+
+---
+
+## Reference: netsupport Comparison
+
+Based on `y:\dev\homecontrol\utils\netsupport`:
+
+### Key Concepts to Adopt
+- Simple socket creation API
+- Non-exclusive listening (SO_REUSEADDR)
+- Clean message handler pattern
+- Automatic cleanup on close
+
+### Differences from netsupport
+- **msgapi**: Integrated into window API (security via flag)
+- **netsupport**: Standalone utility (assumed trusted)
+- **msgapi**: Promise-based async API
+- **netsupport**: May use callback patterns
+- **msgapi**: Cross-platform (Electron, Rust, C#)
+- **netsupport**: Node.js focused
+
+---
+
+## Future Enhancements
+
+### Potential Additions
+- **TCP support**: For reliable, connection-oriented communication
+- **WebSocket support**: For browser-like bidirectional communication
+- **HTTP client**: Simple fetch-like API for web requests
+- **MQTT support**: For IoT messaging patterns
+- **Serial port**: For hardware device communication
+
+### Not Planned (Use Native APIs Instead)
+- File transfers over network (use fs API + HTTP)
+- Complex protocol implementations (use dedicated libraries)
+- VPN/tunnel features (system-level concern)
+
+---
+
+## Open Questions
+
+1. **DNS resolution**: Allow hostnames in send()?
+   - **Recommendation**: YES - trust the user's app, support `socket.send('msg', 8080, 'myserver.local')`
+
+2. **Socket lifetime**: Auto-close on window close, or persist?
+   - **Recommendation**: Auto-close for resource management
+
+3. **Error handling**: Silent fail or throw/reject?
+   - **Recommendation**: Reject promises with descriptive errors
+
+4. **Buffer encoding**: String (UTF-8) vs raw bytes?
+   - **Recommendation**: Support both (string + Uint8Array) ✅ Already in API
+
+5. **Privileged ports**: Allow binding to ports < 1024?
+   - **Recommendation**: YES - if user runs msgview with appropriate permissions, allow it
+
+---
+
+## Timeline Estimate
+
+- **Phase 1 (Core)**: 2-3 weeks per implementation
+  - msgview: 1 week (Node.js dgram is straightforward)
+  - msger: 2 weeks (Tokio async + webview bridge)
+  - msga: 2 weeks (C# + bridge wiring)
+
+- **Phase 2 (Advanced)**: 1 week per implementation
+
+- **Phase 3 (Docs)**: 1 week overall
+
+**Total**: 8-10 weeks for full implementation across all platforms
+
+---
+
+## Status
+
+- [x] Planning document created
+- [ ] msgapidefs types added
+- [ ] msgview implementation
+- [ ] msger implementation
+- [ ] msga implementation
+- [ ] Documentation complete
+- [ ] Testing complete

package/msgapi-plan.md

@@ -0,0 +1,209 @@
+# msgapi Implementation Plan
+
+Shared planning document for msgapi across implementations:
+- **TypeScript**: msgapidefs (this repo) - types/definitions
+- **TypeScript/Electron**: msgview
+- **Rust/wry**: msger
+- **C#/.NET MAUI**: msga (y:\dev\utils\msga)
+
+## Current Status
+
+### Implemented APIs
+
+| API | msgview | msger | msga | Notes |
+|-----|---------|-------|------|-------|
+| **Window Control** |
+| toggleFullscreen() | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
+| setFullscreen(bool) | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
+| minimize() | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
+| maximize() | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
+| setSize(w,h) | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
+| setPosition(x,y) | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
+| setAlwaysOnTop(bool) | ✅ | ✅ | ❌ | |
+| close(result?) | ✅ | ✅ | ⚠️ | msga: basic close only |
+| **File System** |
+| fs.selectFile() | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
+| fs.selectFiles() | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
+| fs.saveFileAs() | ✅ | ✅ | ❌ | |
+| fs.selectFolder() | ✅ | ✅ | ❌ | |
+| fs.read(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
+| fs.write(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
+| fs.list(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
+| fs.exists(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
+| fs.delete(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
+
+Legend: ✅ Implemented | ⚠️ Partial/Not wired | ❌ Not implemented
+
+### msga Wiring Status
+
+The MsgApiBridge.cs file in msga has C# implementations but the JavaScript bridge is not connected:
+- JavaScript injection exists in MainPage.xaml.cs
+- C# handler methods exist in Services/MsgApiBridge.cs
+- Missing: WebView JavaScript-to-C# message handler wiring
+
+---
+
+## Planned Features
+
+### 1. UDP Communication
+
+**Use case**: Local device control, IoT messaging, low-latency communication
+
+```typescript
+interface MsgAPI {
+    udp: {
+        // Send UDP datagram
+        send(host: string, port: number, data: string | Uint8Array): Promise<void>;
+
+        // Listen for UDP datagrams on a port
+        listen(port: number, callback: (data: Uint8Array, sender: {host: string, port: number}) => void): Promise<{close: () => void}>;
+
+        // Send and wait for response (with timeout)
+        sendReceive(host: string, port: number, data: string | Uint8Array, timeoutMs?: number): Promise<Uint8Array>;
+
+        // Broadcast to subnet
+        broadcast(port: number, data: string | Uint8Array): Promise<void>;
+    }
+}
+```
+
+**Implementation notes**:
+- TypeScript: Define types only (browser cannot do UDP)
+- Electron (msgview): Use dgram module
+- Rust (msger): Use std::net::UdpSocket or tokio UDP
+- C#/MAUI (msga): Use System.Net.Sockets.UdpClient
+
+**Security considerations**:
+- Require explicit allowUdp flag or permission prompt
+- Consider port restrictions (no well-known ports < 1024?)
+- Localhost-only mode option
+
+### 2. Enhanced File System
+
+**Use case**: Full file system access for local apps, document management
+
+```typescript
+interface FsExtended {
+    // Already planned in msgapidefs
+    read(path: string): Promise<Uint8Array>;
+    write(path: string, content: string | Uint8Array): Promise<void>;
+    list(path: string): Promise<FsEntry[]>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<void>;
+
+    // New additions
+    mkdir(path: string, recursive?: boolean): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    copy(src: string, dest: string): Promise<void>;
+    stat(path: string): Promise<FsStat>;
+    watch(path: string, callback: (event: FsWatchEvent) => void): Promise<{close: () => void}>;
+}
+
+interface FsEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    size: number;
+    modified: Date;
+}
+
+interface FsStat {
+    size: number;
+    created: Date;
+    modified: Date;
+    accessed: Date;
+    isDirectory: boolean;
+    isFile: boolean;
+    isSymlink: boolean;
+}
+
+interface FsWatchEvent {
+    type: 'create' | 'modify' | 'delete' | 'rename';
+    path: string;
+    newPath?: string; // For rename
+}
+```
+
+**Security considerations**:
+- Require allowFs flag
+- Consider sandboxed paths (app data directory only by default)
+- Full access requires explicit user consent
+
+### 3. System Integration (Lower Priority)
+
+```typescript
+interface MsgAPI {
+    system?: {
+        // Clipboard
+        clipboard: {
+            read(): Promise<string>;
+            write(text: string): Promise<void>;
+            readImage?(): Promise<Uint8Array>;
+            writeImage?(data: Uint8Array): Promise<void>;
+        };
+
+        // Notifications
+        notify(title: string, body: string, options?: NotifyOptions): Promise<void>;
+
+        // Shell/external commands (very restricted)
+        openExternal(url: string): Promise<void>;  // Open in default browser/app
+
+        // Environment info
+        platform: 'windows' | 'macos' | 'linux' | 'android' | 'ios';
+        arch: string;
+        version: string;
+    }
+}
+```
+
+---
+
+## Implementation Priorities
+
+### Phase 1: Wire Up msga (Current)
+1. Connect JavaScript bridge to C# handlers in msga
+2. Test existing window control APIs on Android/Windows
+3. Ensure parity with msgview/msger for basic features
+
+### Phase 2: UDP Support
+1. Add UDP types to msgapidefs
+2. Implement in msger (Rust) - fastest iteration
+3. Port to msgview (Electron)
+4. Port to msga (C#/MAUI)
+
+### Phase 3: Enhanced File System
+1. Add new fs types to msgapidefs
+2. Implement mkdir, rename, copy, stat
+3. Add file watching (platform-specific)
+
+### Phase 4: System Integration
+1. Clipboard support
+2. Notifications
+3. Platform detection
+
+---
+
+## Cross-Implementation Testing
+
+All implementations should pass the same test suite. Use samples.html as base:
+
+```
+msgapidefs/samples.html  - Interactive test page
+msgapidefs/tests/        - Automated tests (TODO)
+```
+
+Test categories:
+- [ ] Window control (fullscreen, minimize, maximize, resize, position)
+- [ ] File dialogs (select file, select files, save as, select folder)
+- [ ] File system read/write (when allowFs enabled)
+- [ ] UDP send/receive (when implemented)
+
+---
+
+## Notes
+
+- msgapi is injected as `window.msgapi` global
+- All async methods return Promises
+- Errors thrown as standard JavaScript errors
+- Platform-specific features return undefined/null if unavailable
+- Version property indicates implementation: `msgapi.version` = "msga/1.0" etc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/msgapidefs",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "TypeScript definitions for msgapi JavaScript API (msgview/msger)",
   "type": "module",
   "main": "./msgapidefs.js",