Guia de publicação cidadã

Este guia explica como publicar textos em Soledade usando terminal, ncat ou nc, e o protocolo SOLED/2 em soledade.city:1915.

Primeira vez? Comece pelo Guia ncat — instalação, registro, o que o ncat faz (e não faz), primeira publicação e assistente com modelos.

Resumo: Como adquirir cidadania · Identidade e credenciais.

O que você precisa

• Handle escolhido no registro, por exemplo maria
• Identidade cidadã salva em ~/.soledade-identidade
• ncat ou nc
• Um arquivo Markdown com seu texto
• Host: soledade.city · Porta: 1915

Placeholders usados neste guia:

HOST=soledade.city
PORTA=1915
CIDADÃO=maria
IDENTIDADE=sua-identidade-aqui

Substitua pelos seus valores reais. Nunca publique sua identidade real neste guia ou em qualquer texto público.

Cidadãos usam ~/.soledade-identidade, não ~/.soledade-token (credenciais).

Testar conectividade

Antes de publicar, confira se a porta 1915 responde — passo a passo em Guia ncat — Testar se a porta responde.

Resumo:

Test-NetConnection soledade.city -Port 1915

nc -zv soledade.city 1915

Se a conexão falhar, registrar ou publicar também falhará (timeout). Abrir ncat sem enviar pacote não entrega credencial.

PATH no servidor e URL no site

O cabeçalho PATH é relativo à pasta content/ no servidor. A URL pública segue o build estático:

O slug na URL é o nome do arquivo sem .md. Publicar de novo no mesmo PATH substitui o arquivo.

Windows: instalando ncat

Opção A — Nmap

1. Baixe e instale o Nmap pelo site oficial do Nmap.
2. Durante a instalação, marque a opção que inclui o Ncat.
3. Teste no PowerShell:

ncat --version

Opção B — WSL ou Git Bash

Se você já usa WSL (Windows Subsystem for Linux) ou prefere ambiente Unix, pode seguir a seção Linux abaixo dentro do WSL.

Linux: instalando ncat ou nc

Debian / Ubuntu

sudo apt update
sudo apt install ncat

Alternativa (pacote netcat tradicional):

sudo apt install netcat-openbsd

Fedora

sudo dnf install nmap-ncat

Arch Linux

sudo pacman -S nmap

Testar:

ncat --version

ou:

nc -h

Criando seu texto

Salve um arquivo .md, por exemplo meu-primeiro-texto.md:

---
title: "Meu primeiro texto"
citizen: "maria"
district: "geral"
tags: ["primeiro-texto", "soledade"]
status: "published"
description: "Meu primeiro texto na cidade de Soledade."
---

# Meu primeiro texto

Esta é minha primeira publicação na cidade textual de Soledade.

Campos do front matter

Textos com status: draft não aparecem na Praça, bairros, arquivo, RSS nem sitemap.

Publicando no Windows com PowerShell

Guarde a identidade em %USERPROFILE%\.soledade-identidade (uma linha, sem espaços extras).

$HostSoledade = "soledade.city"
$PortaSoledade = 1915
$Cidadao = "maria"
$Identidade = Get-Content "$env:USERPROFILE\.soledade-identidade" -Raw
$Identidade = $Identidade.Trim()

$Markdown = Get-Content ".\meu-primeiro-texto.md" -Raw

$Payload = @"
SOLED/2
CITIZEN $Cidadao
IDENTITY $Identidade
PATH citizens/$Cidadao/posts/meu-primeiro-texto.md

$Markdown
.
"@

$Payload | ncat $HostSoledade $PortaSoledade

• O PATH define onde o arquivo será salvo (content/citizens/maria/posts/...).
• A resposta esperada em sucesso:

200 published

O servidor também dispara um rebuild do site; em produção, o texto aparecerá em /@maria/meu-primeiro-texto/.

Publicando no Linux ou macOS com bash

HOST="soledade.city"
PORTA="1915"
CIDADAO="maria"
IDENTIDADE="$(cat ~/.soledade-identidade | tr -d '\r\n')"
ARQUIVO="meu-primeiro-texto.md"
DESTINO="citizens/$CIDADAO/posts/meu-primeiro-texto.md"

{
  echo "SOLED/2"
  echo "CITIZEN $CIDADAO"
  echo "IDENTITY $IDENTIDADE"
  echo "PATH $DESTINO"
  echo
  cat "$ARQUIVO"
  echo "."
} | ncat "$HOST" "$PORTA"

Alternativa com nc:

{
  echo "SOLED/2"
  echo "CITIZEN $CIDADAO"
  echo "IDENTITY $IDENTIDADE"
  echo "PATH $DESTINO"
  echo
  cat "$ARQUIVO"
  echo "."
} | nc "$HOST" "$PORTA"

Editando um texto

Publicar de novo no mesmo PATH substitui o arquivo anterior.

• O slug da URL vem do nome do arquivo (sem .md).
• Se mudar o nome do arquivo no PATH, a URL muda.

Exemplo:

PATH citizens/maria/posts/meu-primeiro-texto.md

Gera a URL:

/@maria/meu-primeiro-texto/

Use o mesmo fluxo PowerShell ou bash, alterando apenas o conteúdo do Markdown.

Apagando um texto

O corpo da mensagem deve ser apenas:

DELETE

Windows (PowerShell)

$HostSoledade = "soledade.city"
$PortaSoledade = 1915
$Cidadao = "maria"
$Identidade = Get-Content "$env:USERPROFILE\.soledade-identidade" -Raw
$Identidade = $Identidade.Trim()

$Payload = @"
SOLED/2
CITIZEN $Cidadao
IDENTITY $Identidade
PATH citizens/$Cidadao/posts/meu-primeiro-texto.md

DELETE
.
"@

$Payload | ncat $HostSoledade $PortaSoledade

Linux (bash)

HOST="soledade.city"
PORTA="1915"
CIDADAO="maria"
IDENTIDADE="$(cat ~/.soledade-identidade | tr -d '\r\n')"
DESTINO="citizens/$CIDADAO/posts/meu-primeiro-texto.md"

{
  echo "SOLED/2"
  echo "CITIZEN $CIDADAO"
  echo "IDENTITY $IDENTIDADE"
  echo "PATH $DESTINO"
  echo
  echo "DELETE"
  echo "."
} | ncat "$HOST" "$PORTA"

Em sucesso, a resposta também é 200 published (comportamento atual do servidor).

Erros comuns

401 invalid identity

Identidade errada, arquivo .soledade-identidade com espaço ou quebra de linha extra, documento trocado ou identidade revogada pelo Prefeito. Confira se você não está usando o protocolo legado por engano — cidadãos usam SOLED/2 com IDENTITY, não token de uma linha após o PATH.

401 invalid token

Resposta do protocolo legado (Prefeito): token em ~/.soledade-token incorreto, ausente ou com espaço/quebra extra. Cidadãos com SOLED/2 recebem 401 invalid identity, não esta mensagem.

403 forbidden

Tentativa de publicar fora da própria casa (citizens/outro/...), cidadão inativo ou banido, ou bairro sem permissão para seu perfil.

400 bad path

Caminho inválido: path absoluto, .., extensão diferente de .md, ou tentativa de sair de content/.

400 missing citizen / 400 missing identity / 400 missing path

Cabeçalhos SOLED/2 incompletos — verifique as linhas CITIZEN, IDENTITY e PATH.

413 payload too large

Texto maior que o limite do servidor (padrão: 128 KiB).

404 not found

Ao apagar (DELETE), o arquivo não existia no PATH indicado.

429 rate limited

Muitas tentativas de registro ou publicação do mesmo IP em pouco tempo. Aguarde e tente de novo.

Sem resposta ou timeout

Porta 1915 inacessível na sua rede ou firewall do servidor. Veja testar conectividade.

Protocolo do Prefeito {#protocolo-do-prefeito} (token legado)

Cidadãos comuns podem ignorar esta seção. Use apenas SOLED/2 e ~/.soledade-identidade.

O Prefeito pode publicar com o protocolo antigo (sem cabeçalhos SOLED/2), usando um token de 64 caracteres hex guardado localmente em:

~/.soledade-token          # Linux / macOS
%USERPROFILE%\.soledade-token   # Windows

O token é obtido pelo administrador da cidade (não aparece ao conectar na 1915 sem pacote). Não commite esse arquivo no Git.

Formato do pacote (legado)

<caminho-relativo-a-content>
<token-uma-linha>
<conteúdo completo do .md>
.

Exemplo PowerShell (Prefeito):

$ncat = "C:\Program Files (x86)\Nmap\ncat.exe"
$remotePath = "citizens/pablo/posts/meu-texto.md"
$token = (Get-Content "$env:USERPROFILE\.soledade-token" -Raw).Trim()
$body = Get-Content ".\meu-texto.md" -Raw
$payload = $remotePath + "`n" + $token + "`n" + $body + "`n.`n"
$payload | & $ncat soledade.city 1915

Resposta esperada: 200 published. Token inválido: 401 invalid token. Se o token do servidor não estiver configurado: 500 mayor not configured.

O Prefeito também pode usar SOLED/2 com identidade cidadã, como qualquer outro handle.

Guia ncat · Identidade cidadã · Regras da cidade · Ajuda