consulcon26-chat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4594cc67cf39cab5eafad671dc2c00f9c116a80d8257dc51ef7fea4c357207af
+  data.tar.gz: f0a17a9961906cfd754dc94c14b22bbd1ae1307e06a54b763eb282cd00059db4
+SHA512:
+  metadata.gz: 9ebe81205c74eb1607749b72f18e61d69173ee0a36df5fcf2a6def3b7f6375f54720b5a3bd7ff390262c5f6bd8fb633a63ffdda596f16cb39e8abae79767407a
+  data.tar.gz: 7bf8be8bf9c93b06eb128e2c1e5f4f54d34421e722cfd6b1551605c5f0299caffa64a429f0747a220b57c51d2f980f9887f926c68eb8ad24eb1e2ed2e275d703

data/README.md

@@ -0,0 +1,270 @@
+# chat
+
+Gema Rails que expone `Chat::RoomComponent`, un [ViewComponent](https://viewcomponent.org)
+que renderiza una sala de chat conectada, directamente desde el navegador,
+a un servidor WebSocket remoto (no usa ActionCable).
+
+## Instalación
+
+Añade al `Gemfile` de la app anfitriona:
+
+```ruby
+gem "consulcon26-chat", require: "chat"
+```
+
+```
+bundle install
+```
+
+El JS se sirve vía Sprockets (asset pipeline clásico), sin importmap ni
+Stimulus — pensado para encajar en apps que ya tienen su propio pipeline de
+JS (como CONSUL) sin tener que añadir nada nuevo a su configuración.
+
+## Configuración
+
+En un inicializador (`config/initializers/chat.rb`):
+
+```ruby
+Chat.configure do |config|
+  config.base_url = "https://chat.midominio.com" # API REST del chat server
+end
+```
+
+## Cargar el JS y el CSS
+
+El engine registra automáticamente `app/assets/javascripts` y
+`app/assets/stylesheets` de la gema en el load path de Sprockets de la app
+anfitriona (y los añade a `config.assets.precompile`, así que tampoco hace
+falta tocar `config/initializers/assets.rb` para producción). No necesitas
+añadir nada al manifest global (`application.js`) ni a ningún `//= require`
+compartido: basta con incluir el script solo en la vista donde renderices
+el componente:
+
+```erb
+<%= javascript_include_tag "chat/room_controller" %>
+<%= stylesheet_link_tag "chat/room_component" %> <%# opcional %>
+
+<%= render Chat::RoomComponent.new(...) %>
+```
+
+`chat/room_controller.js` se auto-inicializa: al cargar, escanea el DOM en
+busca de `[data-chat-room-url]` (lo que pinta el componente) y conecta el
+WebSocket él solo — no hay que registrar ni llamar a nada manualmente. Si
+la app usa Turbolinks, se engancha a `turbolinks:load` para reinicializar
+en cada navegación y a `turbolinks:before-cache` para cerrar el socket
+antes de cachear la página (evita conexiones colgadas al volver atrás); si
+no hay Turbolinks, usa `DOMContentLoaded` como alternativa.
+
+## Uso
+
+```erb
+<%= render Chat::RoomComponent.new(
+  websocket_url: "wss://chat.midominio.com/ws",
+  room: Chat::Client.proposal_room_id(proposal.id),
+  auth_token: session[:chat_auth_token],
+  username: current_user.email
+) %>
+```
+
+### Opciones
+
+| Opción          | Requerido | Descripción                                                                                     |
+|-----------------|-----------|----------------------------------------------------------------------------------------------------|
+| `websocket_url` | sí        | URL del endpoint `/ws` del servidor remoto (`ws://` o `wss://`)                                    |
+| `room`          | no        | Id exacto de la sala (el mismo con el que se creó vía `Chat::Client.create_room`, p. ej. `"proposal:5"`). Se usa al unirse a la sala (`join_room`), al enviar mensajes y como path de `GET /history/:room` |
+| `auth_token`    | no        | JWT devuelto por `Chat::Client.login_user`. Se añade como query param `token` al conectar el WebSocket y se usa para `GET /history/:room` |
+| `username`      | no        | El mismo username con el que este usuario se registró/logueó en el chat server (p. ej. `current_user.email`). **Solo para mostrar**: nunca se envía al servidor — se compara contra el `from` de cada mensaje (historial y en vivo) para etiquetar como "Tú" los mensajes del propio usuario en vez de repetir su username |
+| `height`        | no        | Alto del contenedor (por defecto `"480px"`)                                                       |
+| `placeholder`   | no        | Placeholder del input de texto                                                                    |
+
+## Protocolo de mensajes en el WebSocket
+
+El controlador implementa el protocolo del chat server tal cual, sin
+capa de traducción:
+
+- Al conectar (y en cada reconexión), si hay `room` configurada, envía
+  `{"type":"join_room","room_id":"<room>"}` para suscribirse y empezar a
+  recibir los mensajes de esa sala en tiempo real.
+- Al enviar un mensaje desde el formulario, manda
+  `{"type":"msg","to":"<room>","body":"<texto>"}`. No se envía `user` ni
+  `timestamp`: el servidor identifica al remitente por el JWT de la conexión
+  y asigna `sent_at` al persistir (el mismo criterio que ya usa `/history`).
+- Al recibir un frame `{"type":"msg","from":"...","to":"<room>","body":"..."}`
+  cuyo `to` coincide con la sala, lo añade a la lista de mensajes — así es
+  como ven en vivo los mensajes de **otros** participantes.
+- Al enviar, además, el mensaje se pinta localmente al momento (eco
+  optimista, con "Tú" como autor): el servidor no reenvía al propio
+  remitente su propio mensaje en el broadcast de la room, y no hay acks en
+  el protocolo, así que es la única forma de que el emisor vea su mensaje
+  aparecer sin esperar/depender de ese broadcast.
+- Cualquier otro frame (`presence`, un `msg` de otra sala o 1:1, o algo no
+  reconocido) se ignora silenciosamente en este componente, igual que hace
+  el propio servidor con frames desconocidos.
+
+Si necesitas otro comportamiento (mostrar mensajes 1:1, presence, etc.),
+`window.ChatRoom.initialize` es la función de auto-init; puedes copiar
+`room_controller.js` como base y ajustarlo, o acceder a la instancia ya
+conectada de cualquier elemento vía `el.chatRoomConnection` desde tu propio
+JS.
+
+## Registro y login contra el chat server
+
+Además del componente, la gema expone un cliente HTTP (`Chat::Client`) para
+los dos puntos donde la app anfitriona necesita hablar con el chat server
+por REST, no por WebSocket: dar de alta al usuario y obtener su JWT.
+
+### Registro
+
+Tras el flujo de registro de Devise, registra al usuario en el chat server:
+
+```ruby
+# app/controllers/users/registrations_controller.rb
+class Users::RegistrationsController < Devise::RegistrationsController
+  def create
+    super do |user|
+      next unless user.persisted?
+
+      Chat::Client.register_user(username: user.email, password: params[:user][:password])
+    end
+  end
+end
+```
+
+`params[:user][:password]` es la contraseña en texto plano tal como llegó en
+el formulario: en este punto todavía está disponible en los params de la
+request, pero no en `user` (Devise solo guarda el hash). Es la única
+oportunidad de capturarla para este paso.
+
+Si el username ya existe en el chat server, `Chat::Client.register_user`
+lanza `Chat::UsernameTakenError`; captúrala si quieres degradar sin romper
+el registro en la app:
+
+```ruby
+begin
+  Chat::Client.register_user(username: user.email, password: params[:user][:password])
+rescue Chat::UsernameTakenError, Chat::ServerError, Chat::ConnectionError => e
+  Rails.logger.error("No se pudo registrar #{user.email} en el chat server: #{e.message}")
+end
+```
+
+### Login
+
+Tras el login de Devise, autentica también contra el chat server y guarda
+el JWT en la sesión (pasando `session:`, la propia gema lo guarda en
+`session[:chat_auth_token]`):
+
+```ruby
+# app/controllers/users/sessions_controller.rb
+class Users::SessionsController < Devise::SessionsController
+  def create
+    super do |user|
+      Chat::Client.login_user(username: user.email, password: params[:user][:password], session: session)
+    end
+  end
+end
+```
+
+Después, en cualquier vista, el token guardado está disponible para pasarlo
+al componente:
+
+```erb
+<%= render Chat::RoomComponent.new(
+  websocket_url: "wss://chat.midominio.com/ws",
+  room: Chat::Client.proposal_room_id(proposal.id),
+  auth_token: session[:chat_auth_token],
+  username: current_user.email
+) %>
+```
+
+La clave de sesión es configurable vía `config.session_token_key` (por
+defecto `:chat_auth_token`).
+
+Si las credenciales no son válidas en el chat server,
+`Chat::Client.login_user` lanza `Chat::InvalidCredentialsError` — esto
+puede pasar si el usuario nunca llegó a registrarse allí (p. ej. falló el
+paso de registro); decide tú cómo manejarlo (reintentar el registro,
+loguear el error, etc.), la gema no oculta el fallo.
+
+## Crear una sala de chat
+
+Cuando se crea el elemento de la app anfitriona asociado a una sala (p. ej.
+una `Proposal` de CONSUL), da de alta la sala en el chat server:
+
+```ruby
+class Proposal < ApplicationRecord
+  after_create :create_chat_room
+
+  private
+
+  def create_chat_room
+    Chat::Client.create_room(
+      id: Chat::Client.proposal_room_id(id),
+      title: title,
+      summary: summary,
+      token: ChatServiceToken.fetch # ver nota sobre el token más abajo
+    )
+  rescue Chat::Error => e
+    Rails.logger.error("No se pudo crear la sala de chat para la propuesta #{id}: #{e.message}")
+  end
+end
+```
+
+`Chat::Client.proposal_room_id(id)` construye el id con el formato exacto
+que exige el servidor (`"proposal:<id>"`); pásale el id de la propuesta de
+CONSUL, no se lo pases ya formateado.
+
+La llamada es **idempotente**: si la sala ya existía, el servidor devuelve
+igualmente 201 con los datos de esta petición (no sobreescribe lo que ya
+había en BD) — así que es seguro llamarla también, por ejemplo, en un
+`after_save` si el título/resumen pueden cambiar, sin que eso actualice
+realmente la sala existente en el servidor.
+
+`create_room` valida `id`/`title`/`summary` en el propio cliente antes de
+llamar al servidor (lanza `ArgumentError` si falta alguno o si `id` no seguía
+el formato esperado), porque el servidor no valida esos campos y responde
+500 si los recibe vacíos.
+
+### Sobre el `token` de este endpoint
+
+`POST /rooms` es un endpoint protegido: exige un JWT válido, igual que el
+WebSocket. Si esta llamada la haces desde una request de usuario (p. ej. un
+`before_action` del controller al crear la propuesta) puedes reutilizar
+`session[:chat_auth_token]`. Si la creas en un contexto sin sesión de
+usuario (un rake task, un job, una consola), necesitarás un token de
+servicio propio — la gema no asume cómo lo obtienes en ese caso, solo
+espera que le pases un JWT válido en `token:`.
+
+## Historial de la sala
+
+Al renderizar `Chat::RoomComponent`, si le pasas `room` y `auth_token`, el
+propio componente llama a `GET /history/:room` antes de pintar la vista y
+precarga los mensajes existentes (hasta 200, los últimos por orden
+cronológico) dentro del contenedor de mensajes — así la sala no aparece
+vacía al cargar, y los mensajes que lleguen luego por WebSocket se añaden a
+continuación del historial, sin duplicarlo.
+
+No necesitas hacer nada extra para esto: es automático siempre que ambos
+parámetros estén presentes. Si falta `room` o `auth_token`, o si la
+petición al chat server falla (`Chat::InvalidTokenError`,
+`Chat::ServerError`, `Chat::ConnectionError`), el componente se renderiza
+igualmente sin historial — nunca rompe la página por esto, solo deja un
+`Rails.logger.warn` si algo falló.
+
+Si necesitas el historial fuera del componente (para precachearlo, mostrarlo
+en otro sitio, etc.), también puedes llamarlo directamente:
+
+```ruby
+Chat::Client.history(id: "proposal:5", token: session[:chat_auth_token])
+# => [{ from: "ana", body: "hola!", sent_at: "2026-07-06T16:30:38" }, ...]
+```
+
+(`Chat::Client.history` devuelve el payload tal cual lo da el servidor —
+claves `from`/`body`/`sent_at` — a diferencia de `initial_messages` del
+componente, que ya viene normalizado a `user`/`body` para pintarse igual
+que los mensajes en vivo del WebSocket.)
+
+## Reconexión
+
+Si la conexión se cierra de forma inesperada, el controlador reintenta
+conectar automáticamente (por defecto cada 2000ms, configurable vía el
+atributo `data-chat-room-reconnect-delay`, en milisegundos).

data/app/assets/javascripts/chat/room_controller.js

@@ -0,0 +1,193 @@
+// Sprockets-compatible chat room WebSocket client. No build step, no
+// Stimulus: plain JS that scans the DOM for [data-chat-room-url] elements
+// and wires each one up. Auto-initializes on turbolinks:load (and
+// DOMContentLoaded as a fallback for apps without Turbolinks), and closes
+// sockets on turbolinks:before-cache so navigating away doesn't leak
+// connections.
+(function () {
+  "use strict";
+
+  // Deterministic per-username color (same hash as RoomComponent#author_color
+  // in Ruby), so a given user's name shows in the same color whether it
+  // came from server-rendered history or a live WebSocket message.
+  function authorColor(name) {
+    if (!name) return "#1f6feb";
+
+    var hash = 0;
+    for (var i = 0; i < name.length; i++) {
+      // >>> 0 keeps this an unsigned 32-bit int, matching Ruby's & 0xFFFFFFFF
+      // (plain & would reinterpret it as signed once the top bit is set,
+      // diverging from the Ruby hash from that point on).
+      hash = (hash * 31 + name.charCodeAt(i)) >>> 0;
+    }
+    return "hsl(" + (hash % 360) + ", 65%, 40%)";
+  }
+
+  function ChatRoomConnection(el) {
+    this.el = el;
+    this.url = el.getAttribute("data-chat-room-url");
+    this.room = el.getAttribute("data-chat-room-room");
+    this.authToken = el.getAttribute("data-chat-room-auth-token");
+    this.username = el.getAttribute("data-chat-room-username");
+    this.reconnectDelay = parseInt(el.getAttribute("data-chat-room-reconnect-delay"), 10) || 2000;
+    this.manualClose = false;
+
+    this.messagesEl = el.querySelector("[data-chat-room-target='messages']");
+    this.formEl = el.querySelector("[data-chat-room-target='form']");
+    this.inputEl = el.querySelector("[data-chat-room-target='input']");
+    this.statusEl = el.querySelector("[data-chat-room-target='status']");
+
+    this.onSubmit = this.onSubmit.bind(this);
+    if (this.formEl) this.formEl.addEventListener("submit", this.onSubmit);
+
+    // The server-rendered history is already in the DOM at this point;
+    // scroll to the latest messages instead of leaving the oldest ones in view.
+    this.scrollToBottom();
+
+    this.connect();
+  }
+
+  ChatRoomConnection.prototype.connect = function () {
+    var self = this;
+
+    this.updateStatus("Conectando...");
+    this.socket = new WebSocket(this.buildUrl());
+
+    this.socket.addEventListener("open", function () {
+      self.handleOpen();
+    });
+    this.socket.addEventListener("message", function (event) {
+      self.handleMessage(event);
+    });
+    this.socket.addEventListener("close", function () {
+      self.handleClose();
+    });
+    this.socket.addEventListener("error", function () {
+      self.updateStatus("Error de conexión");
+    });
+  };
+
+  ChatRoomConnection.prototype.buildUrl = function () {
+    var url = new URL(this.url, window.location.href);
+    if (this.authToken) url.searchParams.set("token", this.authToken);
+    return url.toString();
+  };
+
+  ChatRoomConnection.prototype.handleOpen = function () {
+    this.updateStatus("Conectado");
+
+    if (this.room) {
+      this.socket.send(JSON.stringify({ type: "join_room", room_id: this.room }));
+    }
+  };
+
+  ChatRoomConnection.prototype.handleMessage = function (event) {
+    var frame;
+
+    try {
+      frame = JSON.parse(event.data);
+    } catch (_error) {
+      return; // malformed/unknown frames are ignored, same as the server
+    }
+
+    if (frame.type !== "msg") return; // ignore "presence" and anything else
+    if (!this.room || frame.to !== this.room) return; // not this room
+
+    var isOwnMessage = this.username && frame.from === this.username;
+    this.appendMessage({ user: isOwnMessage ? "Tú" : frame.from, body: frame.body });
+  };
+
+  ChatRoomConnection.prototype.handleClose = function () {
+    var self = this;
+
+    this.updateStatus("Desconectado");
+
+    if (!this.manualClose) {
+      setTimeout(function () {
+        self.connect();
+      }, this.reconnectDelay);
+    }
+  };
+
+  ChatRoomConnection.prototype.onSubmit = function (event) {
+    event.preventDefault();
+
+    var body = this.inputEl.value.trim();
+    if (!body || !this.room || !this.socket || this.socket.readyState !== WebSocket.OPEN) return;
+
+    this.socket.send(JSON.stringify({ type: "msg", to: this.room, body: body }));
+    // Optimistic append: the server does not echo the message back to its
+    // own sender, only to the room's other subscribers, and there are no
+    // acks in this protocol — so this is the only way the sender sees
+    // their own message appear.
+    this.appendMessage({ user: "Tú", body: body });
+    this.inputEl.value = "";
+  };
+
+  ChatRoomConnection.prototype.appendMessage = function (message) {
+    var wrapper = document.createElement("div");
+    wrapper.className = "chat-room__message" + (message.user === "Tú" ? " chat-room__message--own" : "");
+
+    var bubble = document.createElement("div");
+    bubble.className = "chat-room__bubble";
+
+    if (message.user && message.user !== "Tú") {
+      var author = document.createElement("div");
+      author.className = "chat-room__message-author";
+      author.style.color = authorColor(message.user);
+      author.textContent = message.user;
+      bubble.appendChild(author);
+    }
+
+    var body = document.createElement("div");
+    body.className = "chat-room__message-body";
+    body.textContent = message.body || "";
+    bubble.appendChild(body);
+
+    wrapper.appendChild(bubble);
+    this.messagesEl.appendChild(wrapper);
+    this.scrollToBottom();
+  };
+
+  ChatRoomConnection.prototype.scrollToBottom = function () {
+    if (this.messagesEl) this.messagesEl.scrollTop = this.messagesEl.scrollHeight;
+  };
+
+  ChatRoomConnection.prototype.updateStatus = function (text) {
+    if (!this.statusEl) return;
+    this.statusEl.textContent = text;
+    this.statusEl.hidden = text === "Conectado";
+  };
+
+  ChatRoomConnection.prototype.disconnect = function () {
+    this.manualClose = true;
+    if (this.socket) this.socket.close();
+  };
+
+  function initialize() {
+    var elements = document.querySelectorAll("[data-chat-room-url]:not([data-chat-room-initialized])");
+
+    for (var i = 0; i < elements.length; i++) {
+      var el = elements[i];
+      el.setAttribute("data-chat-room-initialized", "true");
+      el.chatRoomConnection = new ChatRoomConnection(el);
+    }
+  }
+
+  function teardown() {
+    var elements = document.querySelectorAll("[data-chat-room-initialized]");
+
+    for (var i = 0; i < elements.length; i++) {
+      var el = elements[i];
+      if (el.chatRoomConnection) el.chatRoomConnection.disconnect();
+      el.removeAttribute("data-chat-room-initialized");
+      delete el.chatRoomConnection;
+    }
+  }
+
+  window.ChatRoom = { initialize: initialize };
+
+  document.addEventListener("DOMContentLoaded", initialize);
+  document.addEventListener("turbolinks:load", initialize);
+  document.addEventListener("turbolinks:before-cache", teardown);
+})();

data/app/assets/stylesheets/chat/room_component.css

@@ -0,0 +1,99 @@
+.chat-room {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid #d0d7de;
+  border-radius: 8px;
+  overflow: hidden;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-size: 14px;
+  background: #fff;
+}
+
+.chat-room__messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.chat-room__message {
+  width: 100%;
+  box-sizing: border-box;
+  margin-bottom: 10px;
+  line-height: 1.4;
+}
+
+.chat-room__message--own {
+  text-align: right;
+}
+
+.chat-room__bubble {
+  display: inline-block;
+  max-width: 90%;
+  padding: 8px 12px;
+  border-radius: 14px;
+  background: #f0f2f5;
+  text-align: left;
+  word-wrap: break-word;
+}
+
+.chat-room__message--own .chat-room__bubble {
+  background: #e0ecfe;
+}
+
+.chat-room__message-author {
+  font-weight: 600;
+  margin-bottom: 2px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.chat-room__status {
+  padding: 4px 12px;
+  font-size: 11px;
+  color: #6e7781;
+  border-bottom: 1px solid #eaeef2;
+}
+
+.chat-room__form {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px;
+  border-top: 1px solid #eaeef2;
+}
+
+.chat-room__input {
+  flex: 1;
+  height: 36px !important;
+  margin: 0 !important;
+  padding: 0 10px !important;
+  border: 1px solid #d0d7de !important;
+  border-radius: 6px !important;
+  font-size: inherit;
+  box-sizing: border-box !important;
+}
+
+.chat-room__submit {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 36px !important;
+  height: 36px !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: none !important;
+  border-radius: 6px !important;
+  background: #1f6feb;
+  color: #fff;
+  cursor: pointer;
+  box-sizing: border-box !important;
+}
+
+.chat-room__submit:hover {
+  background: #1a5fd1;
+}

data/app/components/chat/room_component.html.erb

@@ -0,0 +1,37 @@
+<div
+  id="<%= dom_id %>"
+  class="chat-room"
+  style="height: <%= height %>;"
+  data-chat-room-url="<%= websocket_url %>"
+  <% if room.present? %>data-chat-room-room="<%= room %>"<% end %>
+  <% if auth_token.present? %>data-chat-room-auth-token="<%= auth_token %>"<% end %>
+  <% if username.present? %>data-chat-room-username="<%= username %>"<% end %>
+>
+  <div class="chat-room__status" data-chat-room-target="status" hidden></div>
+
+  <div class="chat-room__messages" data-chat-room-target="messages" role="log" aria-live="polite">
+    <% initial_messages.each do |message| %>
+      <div class="chat-room__message<%= " chat-room__message--own" if message[:user] == "Tú" %>">
+        <div class="chat-room__bubble">
+          <% if message[:user].present? && message[:user] != "Tú" %><div class="chat-room__message-author" style="color: <%= author_color(message[:user]) %>;"><%= message[:user] %></div><% end %>
+          <div class="chat-room__message-body"><%= message[:body] %></div>
+        </div>
+      </div>
+    <% end %>
+  </div>
+
+  <form class="chat-room__form" data-chat-room-target="form">
+    <input
+      type="text"
+      class="chat-room__input"
+      data-chat-room-target="input"
+      autocomplete="off"
+      placeholder="<%= placeholder %>"
+    />
+    <button type="submit" class="chat-room__submit" aria-label="Enviar mensaje" title="Enviar mensaje">
+      <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true" focusable="false">
+        <path fill="currentColor" d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z" />
+      </svg>
+    </button>
+  </form>
+</div>

data/app/components/chat/room_component.rb

@@ -0,0 +1,54 @@
+module Chat
+  class RoomComponent < ViewComponent::Base
+    attr_reader :websocket_url, :room, :auth_token, :username, :height, :placeholder
+
+    # `username` is only used for display: it's compared against the
+    # `from` of each history message so the current user's own past
+    # messages show "Tú" instead of their username, matching how live
+    # messages are labeled (see room_controller.js). It's never sent to
+    # the chat server — the server already knows the sender from the JWT.
+    def initialize(websocket_url:, room: nil, auth_token: nil, username: nil, height: "480px",
+                    placeholder: "Escribe un mensaje...")
+      @websocket_url = websocket_url
+      @room = room
+      @auth_token = auth_token
+      @username = username
+      @height = height
+      @placeholder = placeholder
+    end
+
+    def dom_id
+      @dom_id ||= "chat-room-#{object_id}"
+    end
+
+    # Messages already in the room, fetched from GET /history/:room before
+    # rendering, normalized to the same { user:, body: } shape
+    # room_controller.js renders for live WebSocket messages. Empty if
+    # `room` or `auth_token` is missing, or if the history fetch fails —
+    # the chat still renders, just without prior messages.
+    def initial_messages
+      @initial_messages ||= []
+    end
+
+    def before_render
+      return if room.blank? || auth_token.blank?
+
+      @initial_messages = Chat::Client.history(id: room, token: auth_token).map do |message|
+        { user: (message[:from] == username ? "Tú" : message[:from]), body: message[:body] }
+      end
+    rescue Chat::Error => e
+      Rails.logger&.warn("[chat] could not load history for room #{room}: #{e.message}")
+      @initial_messages = []
+    end
+
+    # Deterministic per-username color (same hash as room_controller.js's
+    # authorColor), so a given user's name shows in the same color whether
+    # it comes from server-rendered history or a live WebSocket message.
+    def author_color(name)
+      return "#1f6feb" if name.blank?
+
+      hash = name.each_char.reduce(0) { |acc, char| (acc * 31 + char.ord) & 0xFFFFFFFF }
+      "hsl(#{hash % 360}, 65%, 40%)"
+    end
+  end
+end

data/lib/chat/client.rb

@@ -0,0 +1,166 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Chat
+  # Thin HTTP client for the chat server's REST API (auth_handler.erl):
+  # registers users and exchanges credentials for the JWT later used to
+  # authenticate the WebSocket connection and the other protected endpoints.
+  module Client
+    module_function
+
+    # POST /register
+    #
+    # Returns true on success (201).
+    # Raises Chat::UsernameTakenError on 409, Chat::ServerError otherwise.
+    def register_user(username:, password:)
+      response = post("/register", { username: username, password: password })
+
+      case response.code.to_i
+      when 201
+        true
+      when 409
+        raise UsernameTakenError, error_message(response) || "username already taken"
+      else
+        raise ServerError.new(status: response.code.to_i, body: response.body)
+      end
+    end
+
+    # POST /login
+    #
+    # Returns the JWT (String). If `session` is given, also stores it at
+    # session[Chat.configuration.session_token_key] so the caller doesn't
+    # have to wire that up by hand.
+    #
+    # Raises Chat::InvalidCredentialsError on 401, Chat::ServerError otherwise.
+    def login_user(username:, password:, session: nil)
+      response = post("/login", { username: username, password: password })
+
+      case response.code.to_i
+      when 200
+        token = JSON.parse(response.body)["token"]
+        session[Chat.configuration.session_token_key] = token if session
+        token
+      when 401
+        raise InvalidCredentialsError, error_message(response) || "invalid credentials"
+      else
+        raise ServerError.new(status: response.code.to_i, body: response.body)
+      end
+    end
+
+    # POST /rooms?token=<jwt>
+    #
+    # Idempotent room creation: if `id` already exists server-side, the
+    # server does not fail nor overwrite it, it just echoes back the data
+    # from this request (not what was actually stored). `id` must follow
+    # "proposal:<consul_proposal_id>" — use proposal_room_id to build it.
+    #
+    # Returns a Hash with symbol keys: { id:, title:, summary: }.
+    # Raises ArgumentError if id/title/summary are missing, to avoid the
+    # server's 500 (Erlang match crash on missing keys).
+    # Raises Chat::InvalidTokenError on 401, Chat::ServerError otherwise.
+    def create_room(id:, title:, summary:, token:)
+      validate_room_params!(id: id, title: title, summary: summary)
+
+      response = post("/rooms", { id: id, title: title, summary: summary }, query: { token: token })
+
+      case response.code.to_i
+      when 201
+        JSON.parse(response.body).transform_keys(&:to_sym)
+      when 401
+        raise InvalidTokenError, error_message(response) || "invalid token"
+      else
+        raise ServerError.new(status: response.code.to_i, body: response.body)
+      end
+    end
+
+    # GET /history/<id>?token=<jwt>
+    #
+    # `id` is the same id a room was created with (e.g. "proposal:5"), or a
+    # username for 1:1 chat history. Returns up to 200 messages ordered by
+    # sent_at ASC, as an Array of Hashes with symbol keys: { from:, body:,
+    # sent_at: }. Returns [] if the room/conversation has no messages, or
+    # doesn't exist — the server does not 404 for that.
+    #
+    # Raises Chat::InvalidTokenError on 401, Chat::ServerError otherwise
+    # (including the 500 the server returns on a DB failure).
+    def history(id:, token:)
+      response = get("/history/#{escape_path_segment(id)}", query: { token: token })
+
+      case response.code.to_i
+      when 200
+        JSON.parse(response.body)["messages"].map { |message| message.transform_keys(&:to_sym) }
+      when 401
+        raise InvalidTokenError, error_message(response) || "invalid token"
+      else
+        raise ServerError.new(status: response.code.to_i, body: response.body)
+      end
+    end
+
+    # Builds the room id the chat server expects for a CONSUL proposal.
+    def proposal_room_id(proposal_id)
+      "proposal:#{proposal_id}"
+    end
+
+    def validate_room_params!(id:, title:, summary:)
+      { id: id, title: title, summary: summary }.each do |key, value|
+        raise ArgumentError, "#{key} is required" if value.nil? || value.to_s.strip.empty?
+      end
+
+      return if id.to_s.match?(/\Aproposal:.+\z/)
+
+      raise ArgumentError, "id must follow the \"proposal:<id>\" format, got #{id.inspect}"
+    end
+    private_class_method :validate_room_params!
+
+    def post(path, payload, query: nil)
+      request(Net::HTTP::Post, path, query: query) do |req|
+        req.body = JSON.generate(payload)
+      end
+    end
+    private_class_method :post
+
+    def get(path, query: nil)
+      request(Net::HTTP::Get, path, query: query)
+    end
+    private_class_method :get
+
+    def request(http_method_class, path, query: nil)
+      uri = URI.join(base_url, path)
+      uri.query = URI.encode_www_form(query) if query
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = Chat.configuration.open_timeout
+      http.read_timeout = Chat.configuration.read_timeout
+
+      req = http_method_class.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      yield req if block_given?
+
+      http.request(req)
+    rescue SystemCallError, Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+      raise ConnectionError, e.message
+    end
+    private_class_method :request
+
+    def escape_path_segment(segment)
+      URI::DEFAULT_PARSER.escape(segment.to_s, /[^A-Za-z0-9\-._~:]/)
+    end
+    private_class_method :escape_path_segment
+
+    def base_url
+      Chat.configuration.base_url or
+        raise Error, "Chat.configuration.base_url is not set. Configure it with Chat.configure { |c| c.base_url = \"...\" }."
+    end
+    private_class_method :base_url
+
+    def error_message(response)
+      JSON.parse(response.body)["error"]
+    rescue JSON::ParserError
+      nil
+    end
+    private_class_method :error_message
+  end
+end

data/lib/chat/configuration.rb

@@ -0,0 +1,29 @@
+module Chat
+  class Configuration
+    # Base URL of the external chat server's REST API, e.g. "https://chat.example.com".
+    attr_accessor :base_url
+
+    # Session key the gem writes the JWT to when Chat::Client.login_user is
+    # called with a `session:` argument.
+    attr_accessor :session_token_key
+
+    # Open/read timeouts (seconds) for requests made by Chat::Client.
+    attr_accessor :open_timeout, :read_timeout
+
+    def initialize
+      @session_token_key = :chat_auth_token
+      @open_timeout = 5
+      @read_timeout = 5
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/lib/chat/engine.rb

@@ -0,0 +1,21 @@
+require "rails/engine"
+require "view_component"
+
+module Chat
+  class Engine < ::Rails::Engine
+    # Registers this gem's JS/CSS with the host app's Sprockets asset
+    # pipeline. No importmap/Stimulus involved: room_controller.js is a
+    # plain script meant to be loaded with `javascript_include_tag
+    # "chat/room_controller"`, and it self-initializes.
+    initializer "chat.assets" do |app|
+      next unless app.config.respond_to?(:assets)
+
+      app.config.assets.paths << root.join("app/assets/javascripts")
+      app.config.assets.paths << root.join("app/assets/stylesheets")
+
+      # Included automatically in `rails assets:precompile`, so the host
+      # app doesn't need to touch config/initializers/assets.rb either.
+      app.config.assets.precompile += %w[chat/room_controller.js chat/room_component.css]
+    end
+  end
+end

data/lib/chat/errors.rb

@@ -0,0 +1,29 @@
+module Chat
+  class Error < StandardError; end
+
+  # Raised on POST /register when the server responds 409 Conflict.
+  class UsernameTakenError < Error; end
+
+  # Raised on POST /login when the server responds 401 Unauthorized.
+  class InvalidCredentialsError < Error; end
+
+  # Raised by any token-protected endpoint (POST /rooms, GET /conversations...)
+  # when the server responds 401 Unauthorized because the token is missing,
+  # malformed or expired.
+  class InvalidTokenError < Error; end
+
+  # Raised for any other non-2xx response (including the 500 the server
+  # returns when a request crashes on the Erlang side).
+  class ServerError < Error
+    attr_reader :status, :body
+
+    def initialize(status:, body: nil)
+      @status = status
+      @body = body
+      super("Chat server responded with #{status}#{": #{body}" if body}")
+    end
+  end
+
+  # Raised when the HTTP request itself fails (timeout, DNS, connection refused...).
+  class ConnectionError < Error; end
+end

data/lib/chat/version.rb

@@ -0,0 +1,3 @@
+module Chat
+  VERSION = "0.1.0"
+end

data/lib/chat.rb

@@ -0,0 +1,8 @@
+require "chat/version"
+require "chat/errors"
+require "chat/configuration"
+require "chat/client"
+require "chat/engine"
+
+module Chat
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: consulcon26-chat
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Diego Calvo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Rails engine that ships a ViewComponent chat room UI which connects,
+  directly from the browser, to a remote WebSocket server.
+email: diegocc6@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app/assets/javascripts/chat/room_controller.js
+- app/assets/stylesheets/chat/room_component.css
+- app/components/chat/room_component.html.erb
+- app/components/chat/room_component.rb
+- lib/chat.rb
+- lib/chat/client.rb
+- lib/chat/configuration.rb
+- lib/chat/engine.rb
+- lib/chat/errors.rb
+- lib/chat/version.rb
+homepage: https://rubygems.org/gems/consulcon26-chat
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: ViewComponent chat room backed by a remote WebSocket
+test_files: []