@casual-simulation/aux-websocket-aws 3.8.2-alpha.19511653187 → 3.10.2

package/README.md

@@ -1,3 +1,134 @@
-# AUX Websocket AWS
+# @casual-simulation/aux-websocket-aws
 
-AWS API Gateway Websocket integration with AUX services
+AWS API Gateway WebSocket integration layer for CasualOS (AUX) services, providing specialized handling for AWS API Gateway's WebSocket message size limitations.
+
+## Overview
+
+This package provides a WebSocket client specifically designed for connecting to CasualOS (AUX) services hosted on AWS API Gateway. It extends the standard WebSocket protocol with automatic large message handling through S3 upload/download mechanisms, working around AWS API Gateway's 32KB message size limit.
+
+## Main Export
+
+### `ApiGatewayWebsocketConnectionClient`
+
+A specialized WebSocket client that implements the `ConnectionClient` interface with AWS API Gateway-specific features, particularly automatic handling of large messages through S3 presigned URLs.
+
+**Features:**
+
+-   **Automatic Large Message Handling**: Messages exceeding 32KB are automatically uploaded to S3 via presigned URLs
+-   **Message Size Detection**: Automatically detects when messages exceed AWS API Gateway limits
+-   **Upload/Download Protocol**: Implements a custom protocol for transferring large messages via HTTP
+-   **Transparent to Application**: Large message handling is completely transparent to the application layer
+-   **Connection State Management**: Full connection state tracking via RxJS observables
+-   **Error Handling**: Dedicated error stream for connection and protocol errors
+-   **Type-Safe**: Built with TypeScript for full type safety
+
+**Key Methods:**
+
+-   `connect()` - Establish WebSocket connection to AWS API Gateway
+-   `disconnect()` - Close WebSocket connection
+-   `send(message)` - Send a message (automatically handles large messages)
+-   `event<T>(name)` - Subscribe to specific event types
+-   `connectionState` - Observable of connection state changes
+-   `onError` - Observable of error events
+
+**Usage:**
+
+```typescript
+import { ApiGatewayWebsocketConnectionClient } from '@casual-simulation/aux-websocket-aws';
+import { ReconnectableSocket } from '@casual-simulation/websocket';
+
+// Create underlying WebSocket connection to AWS API Gateway
+const socket = new ReconnectableSocket(
+    'wss://your-api-gateway-id.execute-api.region.amazonaws.com/stage'
+);
+
+// Create AWS API Gateway-aware client
+const client = new ApiGatewayWebsocketConnectionClient(socket);
+
+// Listen for connection state changes
+client.connectionState.subscribe((state) => {
+    console.log('Connected:', state.connected);
+});
+
+// Listen for specific event types
+client.event('device').subscribe((event) => {
+    console.log('Device event:', event);
+});
+
+// Handle errors
+client.onError.subscribe((error) => {
+    console.error('WebSocket error:', error);
+});
+
+// Connect and send messages
+client.connect();
+
+// Small messages sent directly through WebSocket
+client.send({
+    type: 'login',
+    data: { userId: '123' },
+});
+
+// Large messages automatically handled via S3
+client.send({
+    type: 'largeData',
+    payload: veryLargeDataObject, // Automatically uploaded to S3
+});
+```
+
+## Large Message Handling
+
+When a message exceeds the `MAX_MESSAGE_SIZE` (32KB), the client automatically:
+
+1. **Requests Upload URL**: Sends an upload request to the server
+2. **Receives Presigned URL**: Server responds with S3 presigned URL
+3. **Uploads to S3**: Client uploads message data to S3 via HTTP
+4. **Requests Download**: Client notifies server of S3 location
+5. **Server Downloads**: Server downloads from S3 and processes message
+
+This entire process is transparent to the application - just call `send()` with any size message.
+
+## Message Size Limit
+
+```typescript
+MAX_MESSAGE_SIZE = 32_000 bytes (32KB)
+```
+
+Messages larger than this threshold trigger the automatic upload/download protocol.
+
+## WebSocket Event Protocol
+
+The client implements an extended WebSocket event protocol:
+
+-   `WebsocketEventTypes.Message` - Standard message event
+-   `WebsocketEventTypes.UploadRequest` - Request S3 upload URL
+-   `WebsocketEventTypes.UploadResponse` - Receive S3 upload URL
+-   `WebsocketEventTypes.DownloadRequest` - Request download from S3
+-   `WebsocketEventTypes.Error` - Error event
+
+## Dependencies
+
+-   **@casual-simulation/websocket**: Low-level WebSocket management
+-   **@casual-simulation/aux-common**: AUX common types and interfaces
+-   **axios**: HTTP client for S3 uploads/downloads
+-   **rxjs**: Observable-based event handling
+
+## Installation
+
+```bash
+npm install @casual-simulation/aux-websocket-aws
+```
+
+## When to Use This Package
+
+Use this package when:
+
+-   Connecting to CasualOS services hosted on AWS API Gateway
+-   You need to send messages that may exceed 32KB
+-   You want transparent large message handling
+
+Use `@casual-simulation/aux-websocket` instead when:
+
+-   Connecting to non-AWS WebSocket endpoints
+-   All messages are guaranteed to be under 32KB
+-   You don't need AWS-specific features

package/package.json

@@ -1,46 +1,45 @@
 {
-    "name": "@casual-simulation/aux-websocket-aws",
-    "version": "3.8.2-alpha.19511653187",
-    "description": "AWS API Gateway Websocket integration with AUX services",
-    "keywords": [],
-    "author": "Casual Simulation, Inc.",
-    "homepage": "https://github.com/casual-simulation/casualos",
-    "license": "AGPL-3.0-only",
-    "main": "index.js",
-    "types": "index.d.ts",
-    "module": "index",
-    "directories": {
-        "lib": "."
-    },
-    "files": [
-        "/README.md",
-        "/LICENSE.txt",
-        "**/*.js",
-        "**/*.js.map",
-        "**/*.d.ts"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/casual-simulation/casualos.git"
-    },
-    "scripts": {
-        "watch": "tsc --watch",
-        "watch:player": "npm run watch",
-        "build": "echo \"Nothing to do.\"",
-        "test": "jest",
-        "test:watch": "jest --watchAll"
-    },
-    "bugs": {
-        "url": "https://github.com/casual-simulation/casualos/issues"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@casual-simulation/aux-common": "^3.8.2-alpha.19511653187",
-        "@casual-simulation/websocket": "^3.5.3",
-        "axios": "1.7.7",
-        "rxjs": "8.0.0-alpha.14"
-    },
-    "gitHead": "8ba1ed060b9cc71e0af79550480958ce2e930ccb"
-}
+  "name": "@casual-simulation/aux-websocket-aws",
+  "version": "3.10.2",
+  "description": "AWS API Gateway Websocket integration with AUX services",
+  "keywords": [],
+  "author": "Casual Simulation, Inc.",
+  "homepage": "https://github.com/casual-simulation/casualos",
+  "license": "AGPL-3.0-only",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "module": "index",
+  "directories": {
+    "lib": "."
+  },
+  "files": [
+    "/README.md",
+    "/LICENSE.txt",
+    "**/*.js",
+    "**/*.js.map",
+    "**/*.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/casual-simulation/casualos.git"
+  },
+  "bugs": {
+    "url": "https://github.com/casual-simulation/casualos/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@casual-simulation/aux-common": "^3.10.2",
+    "@casual-simulation/websocket": "^3.10.2",
+    "axios": "1.7.7",
+    "rxjs": "8.0.0-alpha.14"
+  },
+  "scripts": {
+    "watch": "tsc --watch",
+    "watch:player": "npm run watch",
+    "build": "echo \"Nothing to do.\"",
+    "test": "jest",
+    "test:watch": "jest --watchAll"
+  }
+}