🏫 CodeRoom

Colaboração de código Python em tempo real na rede da escola.
Sem internet. Sem Git. Sem instalação extra para os alunos.

O que é

CodeRoom é uma extensão para VSCode que permite que professor e alunos editem o mesmo arquivo Python simultaneamente, com sincronização em tempo real via Operational Transformation (OT) — a mesma técnica usada pelo Google Docs. Diferente de soluções baseadas em polling, o OT garante que duas pessoas digitando ao mesmo tempo nunca percam o trabalho uma da outra.

Instalação

Pré-requisitos

• VSCode instalado
• Node.js 18+ instalado (necessário para rodar o servidor)
• Python instalado (para executar os arquivos .py)

Instalar a extensão

Pelo terminal:

code --install-extension coderoom-2.1.0.vsix

Pela interface:

1. Ctrl+Shift+X → Extensões
2. Clique no ... (canto superior direito)
3. Instalar do VSIX... → selecione coderoom-2.1.0.vsix

Após instalar, o ícone do CodeRoom aparece na barra lateral esquerda (Activity Bar).

Como usar em sala de aula

Professor

1. Clique no ícone do CodeRoom na Activity Bar

2. Clique em 🏫 Abrir CodeRoom

3. Acesse ⚙ Professor → senha: 12345

4. No painel do professor:

   • Escolha o IP da rede da escola (Ethernet ou Wi-Fi — evite Radmin/VPN)
   • Copie o endereço e passe para os alunos (quadro, chat, etc.)
   • Veja todas as sessões ativas com preview do código em tempo real
   • Encerre sessões quando necessário

5. Para criar uma sessão:

   • Clique em Criar sessão
   • Defina o nome do grupo e seu nome
   • Opcionalmente, clique em 📂 Abrir para carregar um arquivo .py existente
   • O arquivo é salvo automaticamente na subpasta sessoes/ do workspace

Alunos

1. Abra o CodeRoom
2. Clique em Entrar em sessão
3. Em rede local: digite o endereço do servidor que o professor passou e clique em Buscar No modo Firebase: nada a digitar — as sessões aparecem sozinhas
4. Digite seu nome e clique em Entrar
5. Edite o código — as alterações aparecem para todos em tempo real
6. Clique em ▶ Executar para rodar o Python na própria máquina

Funcionalidades

Modos de conexão

Na tela inicial há um seletor de modo. A escolha fica salva na máquina.

🖧 Rede local (padrão)

Professor e alunos na mesma rede, comunicação direta. Mais rápido (WebSocket, latência de milissegundos), mas depende das portas 7890 e 7891 estarem liberadas entre as máquinas.

🔥 Firebase (para redes restritivas)

Usa o Firebase Realtime Database como intermediário — só HTTPS de saída na porta 443. Funciona em redes com isolamento de cliente, como o Fortinet da escola, que bloqueia tanto a porta 7890 quanto o WebSocket na 7891.

O OT continua exatamente o mesmo: muda apenas por onde as operações trafegam. Os alunos não precisam digitar endereço nenhum — as sessões aparecem sozinhas na lista.

Latência de ~1s (o transporte é por polling do log de operações), contra milissegundos da rede local. Como o OT foi feito justamente para tolerar latência, a edição simultânea continua correta.

Configuração (uma vez): nas regras do Realtime Database, libere o nó coderoom:

{
  "rules": {
    "coderoom": {
      ".read": true,
      ".write": true
    }
  }
}

Arquitetura técnica

Na rede local, o CodeRoom roda dois servidores na máquina do professor:

No modo Firebase, nenhum dos dois é usado. O transporte vira o Realtime Database:

/coderoom/salas/{grupo}        índice leve para a listagem de sessões
/coderoom/dados/{grupo}/
    membros/{nome}             heartbeat — quem cai some da lista sozinho
    chat/{pushId}              append-only, sem corrida entre mensagens
    snapshot                   { content, v } para quem entra depois
    ops/{v}                    log ordenado das operações do OT

Cada operação ocupa uma versão do log via compare-and-swap (if-match: null_etag): duas pessoas nunca gravam na mesma versão, e quem perde a disputa transforma a própria operação contra a vencedora e tenta a próxima versão — que é exatamente o que o servidor ShareDB faz na rede local.

Como o OT funciona:
Em vez de sincronizar o texto completo a cada mudança, o CodeRoom sincroniza operações mínimas: inseriu 'a' na posição 42 ou deletou 3 caracteres a partir da posição 17. Quando dois usuários editam simultaneamente, o servidor transforma as operações para que coexistam sem conflito — exatamente como o Google Docs e o VS Code LiveShare fazem.

Histórico de versões

v2.1.0

• 🔥 Modo Firebase: transporte por HTTPS/443 para redes que bloqueiam as portas 7890/7891 (Fortinet da escola)
• 🐛 Correção no OT: a operação que chegava era aplicada sem ser transformada contra a operação local ainda não confirmada, o que fazia os textos divergirem quando duas pessoas digitavam ao mesmo tempo
• 🐛 Desempate determinístico quando duas pessoas inserem exatamente na mesma posição
• 💓 Heartbeat de membros: quem fecha o VSCode ou cai da rede some da lista sozinho
• ↻ Painel do professor se atualiza sozinho a cada 4s
• 🐛 Botão de encerrar sessão não funcionava: o webview do VSCode não suporta confirm(), então a função saía sem fazer nada. Agora usa o diálogo nativo
• 🐛 Abrir uma segunda janela do VSCode quebrava a extensão (portas 7890/7891 ocupadas sem tratamento de erro)
• 📁 Arquivos das sessões vão para a subpasta sessoes/ em vez da raiz do workspace

v2.0.0

• ⚡ Implementação de OT (Operational Transformation) via ShareDB
• 🔌 WebSocket em tempo real substitui o polling de 1,5s
• Edição simultânea sem conflitos e sem apagar o trabalho de ninguém
• Dois servidores paralelos: HTTP (metadados) + WebSocket (OT)
• Preview do código dos grupos via snapshot do ShareDB

v1.1.1

• Correção: grace period de 2s para não sobrescrever o texto do usuário enquanto digita

v1.1.0

• Ícone na Activity Bar (painel lateral) para abrir o CodeRoom sem Ctrl+Shift+P

v1.0.0

• Lançamento inicial
• Criar/entrar em sessões sem senha
• Editor colaborativo com polling
• Chat por grupo
• Painel do professor com senha
• Seletor de IP (corrige problema com Radmin/VPN)
• Abrir arquivo .py existente para a sessão
• Executar Python no terminal integrado
• Salvar arquivo em disco automaticamente

Firewall (Windows)

Se os alunos não conseguirem conectar, libere as portas no Windows Firewall da máquina do professor:

netsh advfirewall firewall add rule name="CodeRoom HTTP" dir=in action=allow protocol=TCP localport=7890
netsh advfirewall firewall add rule name="CodeRoom WS"   dir=in action=allow protocol=TCP localport=7891

Licença

MIT