hsync 0.30.1 → 0.31.0

package/todo.md

@@ -0,0 +1,324 @@
+# hsync Client - Auth Feature TODO
+
+## Overview
+
+Add HTTP proxy authentication so services without built-in auth (like LM Studio) can be protected when exposed via hsync.
+
+## Design
+
+**Simple case:** One `--token` flag enables auth
+```bash
+hsync -p 1234 --token "my-secret"
+```
+
+**Accepts both:**
+- `Authorization: Bearer my-secret`
+- `Authorization: Basic base64(hsync:my-secret)`
+- URL embedded: `https://hsync:my-secret@xyz.hsync.tech/...`
+
+**Optional username override:**
+```bash
+hsync -p 1234 --token "my-secret" --username "admin"
+# Basic auth expects admin:my-secret
+```
+
+**Programmatic:**
+```javascript
+const con = await hsync.createConnection({
+  port: 1234,
+  token: 'my-secret',
+  username: 'admin'  // optional, defaults to 'hsync'
+});
+```
+
+## Implementation Tasks
+
+### 1. CLI Changes (cli.js)
+
+- [ ] Add `--token <string>` option
+- [ ] Add `--username <string>` option (optional, default: 'hsync')
+- [ ] Pass token/username to connection config
+
+```javascript
+.addOption(new Option('-t, --token <string>', 'auth token for HTTP proxy').env('HSYNC_TOKEN'))
+.addOption(new Option('-u, --username <string>', 'username for Basic auth').env('HSYNC_USERNAME').default('hsync'))
+```
+
+### 2. Connection Changes (connection.js)
+
+- [ ] Accept `token` and `username` in config
+- [ ] After MQTT connect, call `serverPeer.methods.setHttpAuth()` to register auth with server
+- [ ] Store auth config on hsyncClient object
+
+```javascript
+if (config.token) {
+  await hsyncClient.serverPeer.methods.setHttpAuth({
+    token: config.token,
+    username: config.username || 'hsync'
+  });
+}
+```
+
+### 3. Config Changes (config.js)
+
+- [ ] Add `token` and `username` to baseConfig from env vars
+
+```javascript
+token: env.HSYNC_TOKEN,
+username: env.HSYNC_USERNAME || 'hsync',
+```
+
+## Server Dependency
+
+This feature requires hsync-server to implement `setHttpAuth` RPC method and auth checking. See hsync-server/todo.md.
+
+## Testing
+
+- [ ] Test Bearer auth: `curl -H "Authorization: Bearer my-secret" ...`
+- [ ] Test Basic auth: `curl -u hsync:my-secret ...`
+- [ ] Test URL embedded: `curl https://hsync:my-secret@... `
+- [ ] Test wrong token returns 401
+- [ ] Test no token set = no auth checking (open proxy)
+- [ ] Test custom username with Basic auth
+
+## Documentation
+
+- [ ] Update README with auth examples
+- [ ] Add examples for LM Studio use case
+
+---
+
+# Sub-subdomain Routing Feature TODO
+
+## Overview
+
+Route multiple local services through a single hsync connection. One client, multiple services - no need for separate connections per service.
+
+Less overhead: one WebSocket connection instead of many, and one Node process (CLI) instead of multiple instances.
+
+Uses a configurable separator (e.g., `_`) to stay within one subdomain level for wildcard cert compatibility.
+
+## Why Underscore?
+
+Wildcard certs (`*.myhsyncserver.com`) only cover ONE subdomain level:
+```
+✅ myapp.myhsyncserver.com          - covered
+✅ api.myhsyncserver.com            - covered
+❌ api.myapp.myhsyncserver.com      - NOT covered (two levels)
+```
+
+Using underscore keeps it to one level:
+```
+✅ api_myapp.myhsyncserver.com      - covered by *.myhsyncserver.com
+✅ frontend_myapp.myhsyncserver.com - covered
+```
+
+One wildcard cert, unlimited sub-services per client.
+
+## Design
+
+**Example:**
+```
+api_myapp.myhsyncserver.com      → hsync client "myapp" → localhost:3001
+frontend_myapp.myhsyncserver.com → hsync client "myapp" → localhost:3000
+myapp.myhsyncserver.com          → hsync client "myapp" → localhost:3000 (default)
+```
+
+**CLI:**
+```bash
+hsync -p 3000 --subsub api:3001 --subsub frontend:3002
+```
+
+**Programmatic:**
+```javascript
+const con = await hsync.createConnection({
+  port: 3000,  // default
+  subsubs: {
+    'api': 3001,
+    'frontend': 3002
+  }
+});
+```
+
+## Topic Structure
+
+New `websub/` namespace to avoid clashing with existing `web/` close action:
+
+```
+web/{hostname}/{socketId}                    ← no prefix (existing)
+web/{hostname}/{socketId}/close              ← close (existing)
+
+websub/{hostname}/{prefix}/{socketId}        ← with prefix (new)
+websub/{hostname}/{prefix}/{socketId}/close  ← close with prefix (new)
+```
+
+Raw binary payloads throughout - no encoding overhead.
+
+## Implementation Tasks
+
+### 1. CLI Changes (cli.js)
+
+- [ ] Add `--subsub <prefix:port>` option (repeatable)
+
+```javascript
+.addOption(new Option('--subsub <mapping>', 'sub-subdomain prefix to port mapping (e.g., api:3001)').argParser(collectSubsubs))
+
+function collectSubsubs(value, previous) {
+  const [prefix, port] = value.split(':');
+  return { ...previous, [prefix]: parseInt(port, 10) };
+}
+```
+
+### 2. Connection Changes (connection.js)
+
+- [ ] Accept `subsubs` in config
+- [ ] Subscribe to `websub/{hostname}/#` if subsubs configured
+- [ ] Handle `websub/` messages in message handler
+
+```javascript
+if (config.subsubs) {
+  mqConn.subscribe(`websub/${myHostName}/#`);
+}
+
+mqConn.on('message', (topic, message) => {
+  const [name, hostName, ...rest] = topic.split('/');
+
+  if (name === 'websub') {
+    const [prefix, socketId, action] = rest;
+    const port = config.subsubs[prefix] || config.port;
+    webHandler.handleWebRequest(hostName, socketId, action, message, port);
+  }
+  // ... existing web/ handling
+});
+```
+
+### 3. Web Handler Changes (lib/web-handler.js)
+
+- [ ] Accept optional port parameter
+- [ ] Use passed port instead of default config.port
+
+```javascript
+function handleWebRequest(hostName, socketId, action, message, port = defaultPort) {
+  // ... use port for socket.connect()
+}
+```
+
+### 4. Config Changes (config.js)
+
+- [ ] Add subsubs to config structure
+
+## Server Dependency
+
+Requires hsync-server to:
+- Have `HSYNC_SUBSUB_SEPARATOR` configured (e.g., `_`) - feature disabled if not set
+- Parse sub-subdomain prefix (e.g., `api_myapp` → prefix: `api`, base: `myapp`)
+- Route to client based on base hostname
+- Publish to `websub/{base}/{prefix}/{socketId}` when prefix present
+
+See hsync-server/todo.md.
+
+## Testing
+
+- [ ] Test `api_myapp.server.com` forwards to port 3001
+- [ ] Test `frontend_myapp.server.com` forwards to port 3000
+- [ ] Test `myapp.server.com` (no prefix) forwards to default port
+- [ ] Test unknown prefix falls back to default port
+- [ ] Test close action works with prefix
+- [ ] Test existing non-prefixed routing still works
+
+---
+
+# Testing & Linting TODO
+
+## Overview
+
+Add proper test coverage and linting to ensure code quality and catch regressions.
+
+## Testing
+
+### Setup
+
+- [x] Add test framework (vitest or jest) - **DONE**
+- [x] Add test script to package.json - **DONE**
+- [x] Set up test directory structure - **DONE**
+
+```
+hsync/
+  test/
+    unit/
+      config.test.js
+      web-handler.test.js
+      peers.test.js
+      socket-listeners.test.js
+      socket-relays.test.js
+    integration/
+      connection.test.js
+      auth.test.js
+      subsub.test.js
+```
+
+### Unit Tests
+
+- [x] **config.js** - env var parsing, multi-server config - **DONE (3 tests)**
+- [x] **web-handler.js** - request handling, socket management - **DONE (15 tests)**
+- [x] **peers.js** - RPC peer creation, message handling - **DONE (27 tests)**
+- [x] **socket-listeners.js** - listener creation, data forwarding - **DONE (19 tests)**
+- [x] **socket-relays.js** - relay creation, connection handling - **DONE (19 tests)**
+- [x] **socket-map.js** - packet handling - **DONE (5 tests)**
+- [x] **fetch.js** - fetch wrapper - **DONE (11 tests)**
+
+**Total: 99 tests passing**
+
+### Integration Tests
+
+- [ ] Connection to hsync-server (mock or real)
+- [ ] Web request forwarding end-to-end
+- [ ] Auth token validation
+- [ ] Sub-subdomain routing
+- [ ] WebRTC peer connection (if possible to test)
+
+### Test Utilities
+
+- [x] Mock MQTT connection - **DONE**
+- [x] Mock net.Socket - **DONE**
+- [ ] Test fixtures for HTTP requests/responses
+
+## Linting
+
+### Setup
+
+- [x] Add/update ESLint config (eslint.config.js - flat config) - **DONE**
+- [x] Add lint script to package.json - **DONE**
+- [x] Add pre-commit hook (husky + lint-staged) - **DONE**
+
+```json
+{
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.js\"",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+### ESLint Config
+
+- [x] Create `eslint.config.js` with ESLint 9 flat config - **DONE**
+
+### Lint Fixes Needed
+
+- [x] Fix undeclared variables - **DONE**
+- [x] Remove unused variables - **DONE**
+- [x] Consistent quote style (Prettier) - **DONE**
+- [x] Consistent semicolons (Prettier) - **DONE**
+
+## CI/CD
+
+- [x] Add GitHub Actions workflow for tests - **DONE**
+- [x] Add GitHub Actions workflow for linting - **DONE**
+- [x] Run on PR and push to main - **DONE**
+
+See `.github/workflows/ci.yml`

package/vitest.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.test.js'],
+    setupFiles: ['./test/setup.js'],
+    coverage: {
+      provider: 'v8',
+      include: ['**/*.js'],
+      exclude: ['cli.js', 'shell.js', 'dist/**', 'test/**', 'vitest.config.js', 'eslint.config.js'],
+    },
+  },
+});

package/webpack.config.js

@@ -1,19 +1,35 @@
-const path = require('path');
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 const mode = process.env.BUILD_MODE || 'development';
 
-module.exports = {
-  entry: "./hsync-web.js",
+export default {
+  entry: './hsync-web.js',
   output: {
     path: path.resolve(__dirname, 'dist'),
-    filename: mode === 'development' ? 'hsync.js' : 'hsync.min.js'
+    filename: mode === 'development' ? 'hsync.js' : 'hsync.min.js',
+    library: {
+      name: 'hsync',
+      type: 'umd',
+      export: 'default',
+    },
+    globalObject: 'this',
   },
   mode,
+  optimization: {
+    usedExports: true,
+    sideEffects: true,
+  },
   resolve: {
-    alias: {
-    }
+    alias: {},
   },
   node: {
     global: true,
-  }
-};
+  },
+  performance: {
+    hints: false,
+  },
+};