localhostly 0.0.0-stage → 1.1.0

package/lib/protocolo.js

@@ -0,0 +1,96 @@
+// Os quadros que atravessam o WebSocket entre o servidor e o agente.
+//
+// Cada quadro binário: 1 byte de tipo, 4 bytes de id (uint32 BE) e o payload.
+// - inícios (REQ_INICIO, RES_INICIO, WS_ABRIR), WS_FECHAR e ABORTAR: JSON;
+// - corpos (REQ_CORPO, RES_CORPO): bytes, em pedaços de até 64 KiB;
+// - fins (REQ_FIM, RES_FIM): vazios;
+// - WS_DADO: 1 byte (1 = binário, 0 = texto) e os bytes da mensagem;
+// - JANELA: uint32 BE, os bytes que o receptor já entregou ao destino daquele id
+//   (o crédito do controle de fluxo por id, ver lib/fluxo.js).
+// As mensagens de controle (hello, ready, erro) vão em quadros de texto JSON.
+
+export const TIPO = Object.freeze({
+  REQ_INICIO: 1,
+  REQ_CORPO: 2,
+  REQ_FIM: 3,
+  RES_INICIO: 4,
+  RES_CORPO: 5,
+  RES_FIM: 6,
+  WS_ABRIR: 7,
+  WS_DADO: 8,
+  WS_FECHAR: 9,
+  ABORTAR: 10,
+  JANELA: 11,
+});
+
+export const NOME_DO_TIPO = Object.freeze(
+  Object.fromEntries(Object.entries(TIPO).map(([nome, n]) => [n, nome])),
+);
+
+export const CABECALHO = 5;
+export const PEDACO_MAX = 64 * 1024;
+const ID_MAX = 0xffffffff;
+
+const TIPOS_JSON = new Set([TIPO.REQ_INICIO, TIPO.RES_INICIO, TIPO.WS_ABRIR, TIPO.WS_FECHAR, TIPO.ABORTAR]);
+
+function corpoDe(tipo, payload) {
+  if (TIPOS_JSON.has(tipo)) return Buffer.from(JSON.stringify(payload ?? {}), 'utf8');
+  if (tipo === TIPO.JANELA) {
+    if (!Number.isInteger(payload) || payload < 0 || payload > ID_MAX) {
+      throw new RangeError(`janela inválida: ${payload}`);
+    }
+    const b = Buffer.allocUnsafe(4);
+    b.writeUInt32BE(payload, 0);
+    return b;
+  }
+  if (tipo === TIPO.WS_DADO) {
+    const dados = Buffer.isBuffer(payload?.dados) ? payload.dados : Buffer.from(payload?.dados ?? '');
+    const b = Buffer.allocUnsafe(1 + dados.length);
+    b[0] = payload?.binario ? 1 : 0;
+    dados.copy(b, 1);
+    return b;
+  }
+  if (payload == null) return Buffer.alloc(0);
+  if (Buffer.isBuffer(payload)) return payload;
+  if (payload instanceof Uint8Array) return Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
+  throw new TypeError(`payload de ${NOME_DO_TIPO[tipo]} tem de ser bytes`);
+}
+
+export function codificar(tipo, id, payload) {
+  if (!NOME_DO_TIPO[tipo]) throw new RangeError(`tipo desconhecido: ${tipo}`);
+  if (!Number.isInteger(id) || id < 0 || id > ID_MAX) throw new RangeError(`id inválido: ${id}`);
+  const corpo = corpoDe(tipo, payload);
+  const quadro = Buffer.allocUnsafe(CABECALHO + corpo.length);
+  quadro[0] = tipo;
+  quadro.writeUInt32BE(id, 1);
+  corpo.copy(quadro, CABECALHO);
+  return quadro;
+}
+
+export function decodificar(dados) {
+  const buf = Buffer.isBuffer(dados) ? dados : Buffer.from(dados);
+  if (buf.length < CABECALHO) throw new RangeError(`quadro curto: ${buf.length} bytes`);
+  const tipo = buf[0];
+  if (!NOME_DO_TIPO[tipo]) throw new RangeError(`tipo desconhecido: ${tipo}`);
+  const id = buf.readUInt32BE(1);
+  const resto = buf.subarray(CABECALHO);
+  let payload = resto;
+  if (TIPOS_JSON.has(tipo)) {
+    payload = resto.length ? JSON.parse(resto.toString('utf8')) : {};
+  } else if (tipo === TIPO.JANELA) {
+    if (resto.length !== 4) throw new RangeError('janela com tamanho errado');
+    payload = resto.readUInt32BE(0);
+  } else if (tipo === TIPO.WS_DADO) {
+    if (resto.length < 1) throw new RangeError('ws-dado sem marca');
+    payload = { binario: resto[0] === 1, dados: resto.subarray(1) };
+  }
+  return { tipo, id, payload };
+}
+
+// Os códigos que podem ir num quadro de fechamento de WebSocket (RFC 6455, 7.4).
+export function codigoEnviavel(codigo) {
+  return (
+    Number.isInteger(codigo) &&
+    ((codigo >= 1000 && codigo <= 1003) || (codigo >= 1007 && codigo <= 1014) || (codigo >= 3000 && codigo <= 4999))
+  );
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "localhostly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Expose any local port on a public HTTPS URL, behind NAT, without opening ports.",
+  "keywords": [
+    "tunnel",
+    "localhost",
+    "https",
+    "expose",
+    "webhook",
+    "cli"
+  ],
+  "homepage": "https://localhostly.iblabs.io",
+  "type": "module",
+  "bin": {
+    "localhostly": "bin/localhostly.js"
+  },
+  "files": [
+    "bin",
+    "agente",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test \"testes/*.test.mjs\"",
+    "servidor": "node server/index.js",
+    "seo:check": "node scripts/seo/check.mjs"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.22.2"
+  },
+  "devDependencies": {
+    "cheerio": "1.2.0"
+  }
+}