handy-remote-server 1.0.0 → 1.2.0

package/README.md

@@ -10,30 +10,71 @@ The easiest way to run the external inference server is using `npx`:
 npx handy-remote-server
 ```
 
-_(You must have Node.js and npm installed)_
+_(You must have Node.js and Rust/Cargo installed)_
 
 ## Usage
 
-When you run the server for the first time, it will automatically download the **GigaAM v3** model (Russian-only fast architecture model) if it's not present.
+When you run the server for the first time, it will:
 
-It will also generate a unique Bearer API Token for your active session:
+1. **Download the GigaAM v3 model** (~100 MB) with a progress bar:
 
-```bash
-Your API KEY is: xxxxx-xxxxx-xxxxx-xxxxx
+```
+📥 Downloading model...
+   URL:  https://blob.handy.computer/giga-am-v3.int8.onnx
+   Dest: /path/to/models/gigaam.onnx
+
+   ████████████████████░░░░░░░░░░░░░░░░░░░░  52.3%  52.10 MB / 99.60 MB  12.5 MB/s
+
+✅ Download complete in 8.2s
+```
+
+2. **Generate a persistent API key** saved to `~/.handy/api_key`:
+
+```
+======================================================
+Generated a new API KEY (saved to /Users/you/.handy/api_key)
+Your API KEY is: xxxxx...xxxxx
+======================================================
+```
+
+The key persists across restarts. On the next launch, it will be loaded automatically.
+
+3. **Start the server** and log every request in detail:
+
+```
 Handy Remote Server is running on port 3000
+
+[2026-03-07T12:00:00.000Z] ── REQUEST #1 ──────────────────────
+  Method:  POST /transcribe
+  From:    192.168.1.5
+  Auth:    OK
+  [#1]  Audio received: 156.3 KB
+  [#1]  Queued for inference (queue length: 0)
+[2026-03-07T12:00:01.234Z] ── RESPONSE #1 ─────────────────────
+  Status:   200
+  Duration: 1.23s
+  Result:   "Привет, как дела?"
 ```
 
+### Connecting from Handy
+
 1. Open **Handy** on your client machine.
-2. Go to **Settings > General**, select the `Remote` engine.
-3. Provide the Server URL: `http://<your-server-ip>:3000`
-4. Provide the generated Token.
-5. All audio chunks will now be transcribed by the server!
+2. Go to **Settings > Models**, select **Remote Server**.
+3. Go to **Settings > General**, fill in:
+   - **Remote Server URL**: `http://<your-server-ip>:3000`
+   - **API Token**: the generated token
+4. All transcriptions will now be processed by the server!
 
-## How it works
+## Environment Variables
 
-The `handy-remote-server` spins up a tiny Express server alongside a heavily optimized Rust CLI (`rust-infer`) powered by `transcribe-rs`. Audio files are dispatched sequentially from the Node server directly into the Rust engine.
+| Variable         | Default                                     | Description                     |
+| ---------------- | ------------------------------------------- | ------------------------------- |
+| `PORT`           | `3000`                                      | Server port                     |
+| `API_KEY`        | auto-generated, saved to `~/.handy/api_key` | Bearer token for authentication |
+| `INFER_CLI_PATH` | auto-detected                               | Path to the `rust-infer` binary |
 
-### Environment variables
+## How It Works
+
+The `handy-remote-server` spins up a tiny Express server alongside a heavily optimized Rust CLI (`rust-infer`) powered by `transcribe-rs`. Audio files are dispatched sequentially from the Node server directly into the Rust engine.
 
-- `PORT` - defaults to `3000`
-- `API_KEY` - defaults to an auto-generated token in development. Set this to a permanent token for production.
+Currently the server uses the **GigaAM v3** model (Russian-language, fast inference, ~100 MB).

package/dist/index.js

@@ -10,42 +10,115 @@ const child_process_1 = require("child_process");
 const crypto_1 = __importDefault(require("crypto"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const dotenv_1 = __importDefault(require("dotenv"));
 dotenv_1.default.config();
 const app = (0, express_1.default)();
 const port = process.env.PORT || 3000;
-// Set up API KEY
-let API_KEY = process.env.API_KEY;
-if (!API_KEY) {
-    API_KEY = crypto_1.default.randomBytes(32).toString('hex');
+// ── Persistent API Key ────────────────────────────────────────────────
+const handyDir = path_1.default.join(os_1.default.homedir(), '.handy');
+const keyFilePath = path_1.default.join(handyDir, 'api_key');
+function loadOrCreateApiKey() {
+    // 1. Env var takes priority
+    if (process.env.API_KEY) {
+        return process.env.API_KEY;
+    }
+    // 2. Try to load from cached file
+    if (fs_1.default.existsSync(keyFilePath)) {
+        const cached = fs_1.default.readFileSync(keyFilePath, 'utf-8').trim();
+        if (cached.length > 0) {
+            console.log(`\n======================================================`);
+            console.log(`Loaded API KEY from ${keyFilePath}`);
+            console.log(`Your API KEY is: ${cached}`);
+            console.log(`======================================================\n`);
+            return cached;
+        }
+    }
+    // 3. Generate a new one and persist it
+    const newKey = crypto_1.default.randomBytes(32).toString('hex');
+    fs_1.default.mkdirSync(handyDir, { recursive: true });
+    fs_1.default.writeFileSync(keyFilePath, newKey + '\n', { mode: 0o600 });
     console.log(`\n======================================================`);
-    console.log(`Server started without API_KEY in environment variables.`);
-    console.log(`Generated a new token for this session.`);
-    console.log(`Your API KEY is: ${API_KEY}`);
+    console.log(`Generated a new API KEY (saved to ${keyFilePath})`);
+    console.log(`Your API KEY is: ${newKey}`);
     console.log(`======================================================\n`);
+    return newKey;
+}
+const API_KEY = loadOrCreateApiKey();
+// ── Logging helpers ───────────────────────────────────────────────────
+function timestamp() {
+    return new Date().toISOString();
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
 }
-// Ensure models directory exists
+// ── Ensure directories ────────────────────────────────────────────────
 const modelsDir = path_1.default.join(__dirname, '..', 'models');
 if (!fs_1.default.existsSync(modelsDir)) {
     fs_1.default.mkdirSync(modelsDir, { recursive: true });
 }
-// Authentication middleware
+const uploadDir = path_1.default.join(__dirname, '..', 'uploads');
+if (!fs_1.default.existsSync(uploadDir)) {
+    fs_1.default.mkdirSync(uploadDir, { recursive: true });
+}
+// ── Request logging middleware ────────────────────────────────────────
+let requestCounter = 0;
+app.use((req, res, next) => {
+    const reqId = ++requestCounter;
+    const start = Date.now();
+    const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
+    console.log(`\n[${timestamp()}] ── REQUEST #${reqId} ──────────────────────`);
+    console.log(`  Method:  ${req.method} ${req.path}`);
+    console.log(`  From:    ${ip}`);
+    console.log(`  Headers: Content-Type=${req.headers['content-type'] || 'N/A'}, Content-Length=${req.headers['content-length'] || 'N/A'}`);
+    // Store metadata on request for later use
+    req._reqId = reqId;
+    req._startTime = start;
+    req._ip = ip;
+    const originalJson = res.json.bind(res);
+    res.json = function (body) {
+        const duration = Date.now() - start;
+        const status = res.statusCode;
+        console.log(`[${timestamp()}] ── RESPONSE #${reqId} ─────────────────────`);
+        console.log(`  Status:   ${status}`);
+        console.log(`  Duration: ${formatDuration(duration)}`);
+        if (body?.text) {
+            const preview = body.text.length > 100 ? body.text.substring(0, 100) + '...' : body.text;
+            console.log(`  Result:   "${preview}"`);
+        }
+        else if (body?.error) {
+            console.log(`  Error:    ${body.error}`);
+        }
+        console.log(`  ────────────────────────────────────────────────`);
+        return originalJson(body);
+    };
+    next();
+});
+// ── Authentication middleware ─────────────────────────────────────────
 app.use((req, res, next) => {
     const authHeader = req.headers.authorization;
     if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        console.log(`  Auth:     REJECTED (missing/invalid Authorization header)`);
         return res.status(401).json({ error: 'Missing or invalid Authorization header' });
     }
     const token = authHeader.split(' ')[1];
     if (token !== API_KEY) {
+        console.log(`  Auth:     REJECTED (invalid key)`);
         return res.status(403).json({ error: 'Invalid API Key' });
     }
+    console.log(`  Auth:     OK`);
     next();
 });
-// Configure multer to store uploaded files in a temp directory
-const uploadDir = path_1.default.join(__dirname, '..', 'uploads');
-if (!fs_1.default.existsSync(uploadDir)) {
-    fs_1.default.mkdirSync(uploadDir, { recursive: true });
-}
+// ── Multer storage ────────────────────────────────────────────────────
 const storage = multer_1.default.diskStorage({
     destination: function (req, file, cb) {
         cb(null, uploadDir);
@@ -56,20 +129,52 @@ const storage = multer_1.default.diskStorage({
     }
 });
 const upload = (0, multer_1.default)({ storage: storage });
-// Model download logic
+// ── Model download ───────────────────────────────────────────────────
 const GIGAAM_MODEL_URL = 'https://blob.handy.computer/giga-am-v3.int8.onnx';
 const gigaamModelPath = path_1.default.join(modelsDir, 'gigaam.onnx');
 async function downloadFile(url, dest) {
     if (fs_1.default.existsSync(dest))
         return;
-    console.log(`Downloading ${url} to ${dest}...`);
+    console.log(`\n📥 Downloading model...`);
+    console.log(`   URL:  ${url}`);
+    console.log(`   Dest: ${dest}\n`);
     fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
     const response = await fetch(url);
     if (!response.ok)
         throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
-    const arrBuffer = await response.arrayBuffer();
-    fs_1.default.writeFileSync(dest, Buffer.from(arrBuffer));
-    console.log(`Downloaded ${dest}`);
+    const totalBytes = parseInt(response.headers.get('content-length') || '0', 10);
+    let downloadedBytes = 0;
+    const startTime = Date.now();
+    const fileStream = fs_1.default.createWriteStream(dest);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Response body is not readable');
+    const barWidth = 40;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        fileStream.write(Buffer.from(value));
+        downloadedBytes += value.length;
+        // Draw progress bar
+        const percent = totalBytes > 0 ? downloadedBytes / totalBytes : 0;
+        const filled = Math.round(barWidth * percent);
+        const empty = barWidth - filled;
+        const bar = '█'.repeat(filled) + '░'.repeat(empty);
+        const pct = (percent * 100).toFixed(1).padStart(5);
+        const dl = formatBytes(downloadedBytes);
+        const tot = totalBytes > 0 ? formatBytes(totalBytes) : '?';
+        const elapsed = (Date.now() - startTime) / 1000;
+        const speed = elapsed > 0 ? formatBytes(downloadedBytes / elapsed) + '/s' : '';
+        process.stdout.write(`\r   ${bar} ${pct}%  ${dl} / ${tot}  ${speed}   `);
+    }
+    await new Promise((resolve, reject) => {
+        fileStream.end(() => resolve());
+        fileStream.on('error', reject);
+    });
+    const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
+    process.stdout.write('\n');
+    console.log(`\n✅ Download complete in ${totalTime}s\n`);
 }
 async function ensureModels() {
     await downloadFile(GIGAAM_MODEL_URL, gigaamModelPath);
@@ -78,7 +183,6 @@ let inferProcess = null;
 let isReady = false;
 let resolvers = {};
 ensureModels().then(() => {
-    // Spawn the rust background process
     let inferProcessPath = process.env.INFER_CLI_PATH || path_1.default.join(__dirname, '..', 'rust-infer', 'target', 'release', 'rust-infer');
     if (!fs_1.default.existsSync(inferProcessPath)) {
         inferProcessPath = path_1.default.join(__dirname, '..', 'rust-infer', 'target', 'debug', 'rust-infer');
@@ -114,7 +218,7 @@ ensureModels().then(() => {
     console.error('Failed to download models:', e);
     process.exit(1);
 });
-// Queue for pending transcriptions to send them sequentially to the single worker
+// ── Request queue ─────────────────────────────────────────────────────
 const requestQueue = [];
 let isProcessing = false;
 function processQueue() {
@@ -122,38 +226,42 @@ function processQueue() {
         return;
     isProcessing = true;
     const req = requestQueue.shift();
-    // Register resolver
+    console.log(`  [Queue]   Processing request #${req.reqId} (queue length: ${requestQueue.length})`);
     resolvers[req.file] = (result) => {
         delete resolvers[req.file];
         isProcessing = false;
-        // Clean up temp file
         if (fs_1.default.existsSync(req.file)) {
             fs_1.default.unlinkSync(req.file);
         }
         req.resolve(result);
-        // Process next
         process.nextTick(processQueue);
     };
-    // Send path to worker via stdin
     inferProcess.stdin.write(req.file + '\n');
 }
-// The route
+// ── Transcription endpoint ────────────────────────────────────────────
 app.post('/transcribe', express_1.default.raw({ type: 'audio/wav', limit: '50mb' }), async (req, res) => {
+    const reqId = req._reqId || 0;
     if (!isReady) {
+        console.log(`  [#${reqId}]  Rejected: models still loading`);
         return res.status(503).json({ error: 'Models are still loading' });
     }
-    // If using express.raw, the body is a Buffer
     if (!req.body || !Buffer.isBuffer(req.body)) {
+        console.log(`  [#${reqId}]  Rejected: invalid audio body`);
         return res.status(400).json({ error: 'Invalid audio body. Send raw WAV bytes with Content-Type: audio/wav' });
     }
+    const audioSize = req.body.length;
+    console.log(`  [#${reqId}]  Audio received: ${formatBytes(audioSize)}`);
     const tempFilePath = path_1.default.join(uploadDir, `upload-${Date.now()}-${Math.random().toString(36).substring(7)}.wav`);
     fs_1.default.writeFileSync(tempFilePath, req.body);
+    console.log(`  [#${reqId}]  Queued for inference (queue length: ${requestQueue.length})`);
     const result = await new Promise((resolve) => {
-        requestQueue.push({ file: tempFilePath, resolve });
+        requestQueue.push({ file: tempFilePath, resolve, reqId });
         processQueue();
     });
     res.json(result);
 });
+// ── Start server ──────────────────────────────────────────────────────
 app.listen(port, () => {
-    console.log(`Handy Remote Server is running on port ${port}`);
+    console.log(`\nHandy Remote Server is running on port ${port}`);
+    console.log(`Waiting for requests...\n`);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handy-remote-server",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Remote Transcription Server for Handy",
   "main": "dist/index.js",
   "bin": {