localhostly 0.0.0-stage → 1.0.0

package/agente/tunel.js

@@ -0,0 +1,335 @@
+// O agente: uma conexão de saída ao servidor e cada requisição reproduzida na porta local.
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+import { performance } from 'node:perf_hooks';
+import WebSocket from 'ws';
+import { Canal } from '../lib/canal.js';
+import { filtrar, paraObjeto, sem, valor } from '../lib/cabecalhos.js';
+import { entregar, Remetente, segurarWs } from '../lib/fluxo.js';
+import { codigoEnviavel, TIPO } from '../lib/protocolo.js';
+
+export const SERVIDOR_PADRAO = 'wss://localhostly.iblabs.io/agent';
+export const RECUO_MIN = 1_000;
+export const RECUO_MAX = 60_000;
+export const JITTER = 0.2;
+
+// A espera antes da tentativa n (0 = a primeira depois da queda): min(max, min·2^n) ± 20 %, nunca acima de max
+// (com a rede de volta, o túnel volta em até um minuto).
+export function recuo(n, { min = RECUO_MIN, max = RECUO_MAX, jitter = JITTER, aleatorio = Math.random } = {}) {
+  const base = Math.min(max, min * 2 ** Math.min(n, 30));
+  return Math.round(Math.min(max, base * (1 + (aleatorio() * 2 - 1) * jitter)));
+}
+
+function paginaErro(alvo, erro) {
+  return (
+    '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>502 · localhostly</title></head>' +
+    '<body style="font:16px/1.5 system-ui,sans-serif;max-width:36rem;margin:15vh auto;padding:0 1rem">' +
+    `<h1>502 · Local app unreachable</h1><p>localhostly could not reach <code>http://${alvo}</code>` +
+    ` (${String(erro.code ?? erro.message).replace(/[<>&]/g, '')}). Is it running?</p></body></html>\n`
+  );
+}
+
+// alvo: { host, porta } do app local; hostCabecalho: o Host que o app recebe (null = o original).
+export class Tunel extends EventEmitter {
+  constructor({
+    servidor = SERVIDOR_PADRAO,
+    token = null,
+    alvo,
+    hostCabecalho = null,
+    senha = null,
+    reconectar = true,
+    recuoMin = RECUO_MIN,
+    recuoMax = RECUO_MAX,
+    silencioMs = 90_000,
+    handshakeMs = 15_000,
+    // a sessão de antes ({ nome, tokenSessao }): a primeira conexão já pede o mesmo nome
+    sessao = null,
+    // recusado pelo servidor (sem token, limite de túneis…): tenta de novo no recuo em vez de parar (o serviço)
+    insistir = false,
+  }) {
+    super();
+    this.servidor = servidor;
+    this.token = token;
+    this.alvo = alvo;
+    this.hostCabecalho = hostCabecalho;
+    this.senha = senha;
+    this.reconectar = reconectar;
+    this.silencioMs = silencioMs;
+    this.handshakeMs = handshakeMs;
+    this.recuoMin = recuoMin;
+    this.recuoMax = recuoMax;
+    this.insistir = insistir;
+    this.tentativas = 0; // falhas seguidas desde o último "ready"
+    // { nome, tokenSessao } do último "ready": a reconexão retoma o mesmo nome
+    this.sessao = sessao?.nome && sessao?.tokenSessao ? { nome: sessao.nome, tokenSessao: sessao.tokenSessao } : null;
+    this.fechado = false;
+    this.nome = null;
+    this.url = null;
+    this.ws = null;
+    this.agenteHttp = new http.Agent({ keepAlive: true });
+    this.timerReconexao = null;
+  }
+
+  get enderecoLocal() {
+    const h = this.alvo.host.includes(':') ? `[${this.alvo.host}]` : this.alvo.host;
+    return `${h}:${this.alvo.porta}`;
+  }
+
+  abrir() {
+    this.#conectar();
+    return this;
+  }
+
+  // Espera o primeiro "ready" (ou o erro do servidor).
+  pronto() {
+    if (this.nome) return Promise.resolve({ nome: this.nome, url: this.url });
+    return new Promise((resolve, reject) => {
+      const ok = (info) => {
+        this.off('recusado', falha);
+        resolve(info);
+      };
+      const falha = (erro) => {
+        this.off('pronto', ok);
+        reject(erro);
+      };
+      this.once('pronto', ok);
+      this.once('recusado', falha);
+    });
+  }
+
+  fechar() {
+    this.fechado = true;
+    clearTimeout(this.timerReconexao);
+    this.ws?.terminate();
+    this.agenteHttp.destroy();
+  }
+
+  #conectar() {
+    // o prazo do aperto de mão: com a rede voltando, um SYN perdido não segura a tentativa por minutos
+    const ws = new WebSocket(this.servidor, {
+      perMessageDeflate: false,
+      maxPayload: 1024 * 1024,
+      handshakeTimeout: this.handshakeMs,
+    });
+    this.ws = ws;
+    const canal = new Canal(ws);
+    let recusado = false;
+    const pedido = this.sessao?.nome ?? null;
+    let silencio = null;
+    const vigiar = () => {
+      clearTimeout(silencio);
+      silencio = setTimeout(() => ws.terminate(), this.silencioMs);
+    };
+
+    ws.on('open', () => {
+      vigiar();
+      canal.enviarControle({
+        t: 'hello',
+        token: this.token,
+        nome: this.sessao?.nome ?? null,
+        tokenSessao: this.sessao?.tokenSessao ?? null,
+        host: this.hostCabecalho,
+        password: this.senha,
+      });
+    });
+    ws.on('ping', vigiar);
+    ws.on('message', vigiar);
+    ws.on('error', (erro) => this.emit('aviso', erro));
+    canal.on('invalido', () => ws.terminate());
+    canal.on('controle', (msg) => {
+      if (msg.t === 'ready') {
+        this.tentativas = 0;
+        this.nome = msg.nome;
+        this.url = msg.url;
+        this.sessao = msg.tokenSessao ? { nome: msg.nome, tokenSessao: msg.tokenSessao } : null;
+        // pediu um nome e veio outro (a reserva acabou, o servidor reiniciou): segue com o novo e avisa
+        if (pedido && pedido !== msg.nome) this.emit('nome_trocado', { de: pedido, para: msg.nome });
+        this.emit('pronto', {
+          nome: msg.nome,
+          url: msg.url,
+          retomado: Boolean(msg.retomado),
+          tokenSessao: msg.tokenSessao ?? null,
+        });
+      } else if (msg.t === 'erro') {
+        recusado = true;
+        const erro = new Error(msg.mensagem || msg.codigo);
+        erro.codigo = msg.codigo;
+        this.emit('recusado', erro);
+      }
+    });
+    canal.aoAbrir = (quadro) => {
+      if (quadro.tipo === TIPO.REQ_INICIO) this.#requisicao(canal, quadro);
+      else this.#websocket(canal, quadro);
+    };
+    ws.on('close', () => {
+      clearTimeout(silencio);
+      const tinhaNome = this.nome;
+      this.nome = null;
+      this.url = null;
+      if (this.fechado) return;
+      if (tinhaNome) this.emit('caiu', { nome: tinhaNome });
+      if ((recusado && !this.insistir) || !this.reconectar) {
+        this.emit('fim');
+        return;
+      }
+      const espera = recuo(this.tentativas++, { min: this.recuoMin, max: this.recuoMax });
+      this.emit('reconectando', { emMs: espera, tentativa: this.tentativas });
+      this.timerReconexao = setTimeout(() => this.#conectar(), espera);
+    });
+  }
+
+  #requisicao(canal, { id, payload }) {
+    const inicio = performance.now();
+    const { metodo, caminho, cabecalhos = [] } = payload;
+    const remetente = new Remetente(canal, id, TIPO.RES_CORPO, TIPO.RES_FIM);
+    let respondeu = false;
+    let acabou = false;
+    let status = 0;
+
+    const terminar = () => {
+      if (acabou) return;
+      acabou = true;
+      remetente.encerrar();
+      canal.soltar(id);
+      this.emit('requisicao', { metodo, caminho, status, ms: Math.round(performance.now() - inicio) });
+    };
+
+    const local = http.request({
+      host: this.alvo.host,
+      port: this.alvo.porta,
+      method: metodo,
+      path: caminho,
+      headers: cabecalhos,
+      agent: this.agenteHttp,
+    });
+
+    canal.registrar(id, {
+      quadro: ({ tipo, payload: p }) => {
+        if (tipo === TIPO.REQ_CORPO) entregar(local, p, canal, id);
+        else if (tipo === TIPO.REQ_FIM) local.end();
+        else if (tipo === TIPO.JANELA) remetente.credito(p);
+        else if (tipo === TIPO.ABORTAR) {
+          status = status || 499;
+          local.destroy();
+          terminar();
+        }
+      },
+      fechou: () => {
+        local.destroy();
+        terminar();
+      },
+    });
+
+    local.on('response', (res) => {
+      respondeu = true;
+      status = res.statusCode;
+      canal.enviar(TIPO.RES_INICIO, id, {
+        status: res.statusCode,
+        mensagem: res.statusMessage,
+        cabecalhos: filtrar(res.rawHeaders),
+      });
+      remetente.ligar(res);
+      res.on('end', terminar);
+      res.on('error', () => {
+        if (!acabou) canal.enviar(TIPO.ABORTAR, id, { motivo: 'local' });
+        terminar();
+      });
+    });
+
+    local.on('error', (erro) => {
+      if (acabou) return;
+      if (!respondeu) {
+        status = 502;
+        const corpo = Buffer.from(paginaErro(this.enderecoLocal, erro));
+        canal.enviar(TIPO.RES_INICIO, id, {
+          status: 502,
+          cabecalhos: ['Content-Type', 'text/html; charset=utf-8', 'Content-Length', String(corpo.length)],
+        });
+        canal.enviar(TIPO.RES_CORPO, id, corpo);
+        canal.enviar(TIPO.RES_FIM, id);
+      } else {
+        canal.enviar(TIPO.ABORTAR, id, { motivo: 'local' });
+      }
+      terminar();
+    });
+  }
+
+  #websocket(canal, { id, payload }) {
+    const inicio = performance.now();
+    const { caminho = '/', cabecalhos = [] } = payload;
+    const protocolos = (valor(cabecalhos, 'sec-websocket-protocol') ?? '')
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean);
+    const headers = paraObjeto(sem(cabecalhos, ['sec-websocket-protocol']));
+    let aberto = false;
+    let acabou = false;
+
+    const terminar = (status) => {
+      if (acabou) return;
+      acabou = true;
+      canal.soltar(id);
+      if (!aberto) {
+        this.emit('requisicao', { metodo: 'WS', caminho, status, ms: Math.round(performance.now() - inicio) });
+      }
+    };
+
+    const local = new WebSocket(`ws://${this.enderecoLocal}${caminho}`, protocolos, {
+      headers,
+      perMessageDeflate: false,
+    });
+
+    canal.registrar(id, {
+      quadro: ({ tipo, payload: p }) => {
+        if (tipo === TIPO.WS_DADO) {
+          if (local.readyState === WebSocket.OPEN) local.send(p.dados, { binary: p.binario });
+        } else if (tipo === TIPO.WS_FECHAR) {
+          acabou = true;
+          canal.soltar(id);
+          if (codigoEnviavel(p.codigo)) local.close(p.codigo, String(p.motivo ?? '').slice(0, 120));
+          else local.close();
+        } else if (tipo === TIPO.ABORTAR) {
+          local.terminate();
+          terminar(499);
+        }
+      },
+      fechou: () => {
+        local.terminate();
+        terminar(499);
+      },
+    });
+
+    local.on('open', () => {
+      aberto = true;
+      canal.enviar(TIPO.RES_INICIO, id, { status: 101, protocolo: local.protocol || null });
+      this.emit('requisicao', { metodo: 'WS', caminho, status: 101, ms: Math.round(performance.now() - inicio) });
+    });
+    local.on('unexpected-response', (req, res) => {
+      if (!acabou) {
+        canal.enviar(TIPO.RES_INICIO, id, { status: res.statusCode, motivo: res.statusMessage });
+        terminar(res.statusCode);
+      }
+      res.resume();
+      req.destroy();
+    });
+    local.on('message', (dados, binario) => {
+      canal.enviar(TIPO.WS_DADO, id, { binario, dados: Buffer.isBuffer(dados) ? dados : Buffer.concat(dados) });
+      segurarWs(local, canal);
+    });
+    local.on('error', (erro) => {
+      if (acabou) return;
+      if (!aberto) canal.enviar(TIPO.RES_INICIO, id, { status: 502, motivo: String(erro.code ?? erro.message) });
+      else canal.enviar(TIPO.WS_FECHAR, id, { codigo: 1011, motivo: 'local error' });
+      terminar(502);
+    });
+    local.on('close', (codigo, motivo) => {
+      if (acabou) return;
+      canal.enviar(TIPO.WS_FECHAR, id, { codigo, motivo: motivo.toString('utf8') });
+      terminar(101);
+    });
+  }
+}
+
+export function abrirTunel(opcoes) {
+  return new Tunel(opcoes).abrir();
+}

package/bin/localhostly.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { principal } from '../agente/cli.js';
+
+process.exitCode = await principal();
+process.exit();

package/lib/cabecalhos.js

@@ -0,0 +1,63 @@
+// Cabeçalhos em lista plana [nome, valor, nome, valor, ...], como o rawHeaders do Node:
+// preserva repetidos (Set-Cookie) e a grafia original.
+
+const SALTO = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+// Tira os de salto (hop-by-hop), os citados no Connection e os extras pedidos.
+export function filtrar(lista, extras = []) {
+  const fora = new Set(extras.map((n) => n.toLowerCase()));
+  for (let i = 0; i < lista.length; i += 2) {
+    if (String(lista[i]).toLowerCase() === 'connection') {
+      for (const n of String(lista[i + 1]).split(',')) {
+        const nome = n.trim().toLowerCase();
+        if (nome) fora.add(nome);
+      }
+    }
+  }
+  const saida = [];
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    const nome = String(lista[i]);
+    const baixo = nome.toLowerCase();
+    if (SALTO.has(baixo) || fora.has(baixo)) continue;
+    saida.push(nome, String(lista[i + 1]));
+  }
+  return saida;
+}
+
+export function valor(lista, nome) {
+  const alvo = nome.toLowerCase();
+  const achados = [];
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    if (String(lista[i]).toLowerCase() === alvo) achados.push(String(lista[i + 1]));
+  }
+  return achados.length ? achados.join(', ') : undefined;
+}
+
+export function sem(lista, nomes) {
+  const fora = new Set(nomes.map((n) => n.toLowerCase()));
+  const saida = [];
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    if (!fora.has(String(lista[i]).toLowerCase())) saida.push(lista[i], lista[i + 1]);
+  }
+  return saida;
+}
+
+// Lista plana -> objeto (repetidos juntados por vírgula), para APIs que só aceitam objeto.
+export function paraObjeto(lista) {
+  const obj = {};
+  for (let i = 0; i + 1 < lista.length; i += 2) {
+    const nome = String(lista[i]).toLowerCase();
+    obj[nome] = nome in obj ? `${obj[nome]}, ${lista[i + 1]}` : String(lista[i + 1]);
+  }
+  return obj;
+}

package/lib/canal.js

@@ -0,0 +1,87 @@
+// O canal: um WebSocket entre servidor e agente com vários fluxos (ids) em voo.
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { codificar, decodificar, TIPO } from './protocolo.js';
+
+const ABRE_FLUXO = new Set([TIPO.REQ_INICIO, TIPO.WS_ABRIR]);
+
+export class Canal extends EventEmitter {
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    this.fluxos = new Map();
+    this.proximoId = 1;
+    this.aoAbrir = null; // (quadro) => void, no lado que recebe pedidos (o agente)
+    ws.on('message', (dados, binario) => this.#receber(dados, binario));
+    ws.on('close', () => this.#fechou());
+  }
+
+  get aberto() {
+    return this.ws.readyState === WebSocket.OPEN;
+  }
+
+  get bufferedAmount() {
+    return this.ws.bufferedAmount;
+  }
+
+  novoId() {
+    const id = this.proximoId;
+    this.proximoId = this.proximoId >= 0xffffffff ? 1 : this.proximoId + 1;
+    return id;
+  }
+
+  registrar(id, fluxo) {
+    this.fluxos.set(id, fluxo);
+  }
+
+  soltar(id) {
+    this.fluxos.delete(id);
+  }
+
+  enviar(tipo, id, payload) {
+    if (!this.aberto) return false;
+    this.ws.send(codificar(tipo, id, payload), { binary: true });
+    return true;
+  }
+
+  enviarControle(msg) {
+    if (!this.aberto) return false;
+    this.ws.send(JSON.stringify(msg));
+    return true;
+  }
+
+  #receber(dados, binario) {
+    if (!binario) {
+      let msg;
+      try {
+        msg = JSON.parse(dados.toString('utf8'));
+      } catch {
+        this.emit('invalido', new Error('controle que não é JSON'));
+        return;
+      }
+      this.emit('controle', msg);
+      return;
+    }
+    let quadro;
+    try {
+      quadro = decodificar(dados);
+    } catch (erro) {
+      this.emit('invalido', erro);
+      return;
+    }
+    const fluxo = this.fluxos.get(quadro.id);
+    if (fluxo) {
+      fluxo.quadro(quadro);
+    } else if (ABRE_FLUXO.has(quadro.tipo) && this.aoAbrir) {
+      this.aoAbrir(quadro);
+    }
+    // quadro de id que já acabou (janela atrasada, corpo depois do abortar): ignorado
+  }
+
+  #fechou() {
+    const fluxos = [...this.fluxos.values()];
+    this.fluxos.clear();
+    for (const fluxo of fluxos) fluxo.fechou?.();
+    this.emit('fechou');
+  }
+}

package/lib/fluxo.js

@@ -0,0 +1,100 @@
+// Controle de fluxo: o corpo nunca fica inteiro em memória.
+//
+// Por id: quem manda tem JANELA_INICIAL bytes de crédito; o receptor devolve o crédito
+// (quadro JANELA) só quando o pedaço foi entregue ao destino (o callback do write),
+// então um visitante lento ou um app local lento seguram só o próprio fluxo.
+// No canal inteiro: a fonte pausa quando o WebSocket acumula mais de ALTO bytes no
+// buffer de saída e retoma abaixo de BAIXO.
+import { PEDACO_MAX, TIPO } from './protocolo.js';
+
+export const JANELA_INICIAL = 2 * 1024 * 1024;
+export const ALTO = 4 * 1024 * 1024;
+export const BAIXO = 1024 * 1024;
+const ESPERA_MS = 10;
+
+export class Remetente {
+  constructor(canal, id, tipoCorpo, tipoFim) {
+    this.canal = canal;
+    this.id = id;
+    this.tipoCorpo = tipoCorpo;
+    this.tipoFim = tipoFim;
+    this.saldo = JANELA_INICIAL;
+    this.fonte = null;
+    this.parado = false;
+    this.encerrado = false;
+    this.timer = null;
+  }
+
+  ligar(fonte) {
+    this.fonte = fonte;
+    fonte.on('data', (pedaco) => this.#dados(pedaco));
+    fonte.on('end', () => {
+      if (!this.encerrado) this.canal.enviar(this.tipoFim, this.id);
+    });
+  }
+
+  credito(n) {
+    this.saldo += n;
+    this.#tentarRetomar();
+  }
+
+  encerrar() {
+    this.encerrado = true;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  #dados(pedaco) {
+    if (this.encerrado) return;
+    for (let i = 0; i < pedaco.length; i += PEDACO_MAX) {
+      const parte = pedaco.subarray(i, i + PEDACO_MAX);
+      this.canal.enviar(this.tipoCorpo, this.id, parte);
+      this.saldo -= parte.length;
+    }
+    if (this.saldo <= 0 || this.canal.bufferedAmount > ALTO) {
+      if (!this.parado) {
+        this.parado = true;
+        this.fonte.pause();
+      }
+      this.#tentarRetomar();
+    }
+  }
+
+  #tentarRetomar() {
+    if (!this.parado || this.encerrado || this.saldo <= 0) return;
+    if (this.canal.bufferedAmount > BAIXO) {
+      if (!this.timer) {
+        this.timer = setTimeout(() => {
+          this.timer = null;
+          this.#tentarRetomar();
+        }, ESPERA_MS);
+      }
+      return;
+    }
+    this.parado = false;
+    this.fonte.resume();
+  }
+}
+
+// Entrega um pedaço ao destino e devolve o crédito quando ele saiu.
+export function entregar(destino, pedaco, canal, id) {
+  if (destino.destroyed || destino.writableEnded) return;
+  destino.write(pedaco, (erro) => {
+    if (!erro) canal.enviar(TIPO.JANELA, id, pedaco.length);
+  });
+}
+
+// Mensagens de WebSocket: pausa a fonte enquanto o canal está cheio.
+export function segurarWs(ws, canal) {
+  if (canal.bufferedAmount <= ALTO || ws.isPaused) return;
+  ws.pause();
+  const conferir = () => {
+    if (ws.readyState > 1) return;
+    if (canal.aberto && canal.bufferedAmount > BAIXO) {
+      setTimeout(conferir, ESPERA_MS);
+      return;
+    }
+    ws.resume();
+  };
+  setTimeout(conferir, ESPERA_MS);
+}

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))
+  );
+}