DEV Community

Cover image for Calcule o CID agora, publique no IPFS depois
Pedro Pietroluongo
Pedro Pietroluongo

Posted on Edited on

Calcule o CID agora, publique no IPFS depois

Como o Git separa commit de push, um IPFS virtual em Java separa endereçamento de conteúdo e publicação — e isso muda o que dá para fazer antes de expor um arquivo na rede.

O IPFS tem uma promessa elegante: o endereço de um arquivo depende só do conteúdo. Esse endereço é o CID. Qualquer pessoa, em qualquer lugar, pode pedi-lo e conferir se o que chegou é exatamente o que o CID descreve.

Na prática, num nó comum, obter esse CID e colocá-lo na rede são o mesmo passo. Você roda ipfs add, o hash é calculado — e o arquivo já começa a ser anunciado para outros peers. Não existe um "commit" local. Adicionar é publicar.

Isso me incomodava. Eu queria o identificador estável, conferível, igual ao do resto do ecossistema IPFS, sem, naquele momento, expor o conteúdo. Queria montar um pacote com vários arquivos se referenciando uns aos outros, trocar de versão, e só então decidir se aquilo ia para a rede. Com um nó tradicional, não há esse meio-termo.

O Nebulus, originalmente uma biblioteca JavaScript, parte exatamente dessa separação. Ele trata o IPFS como o Git trata um repositório: o CID é calculado offline, e o push é explícito. Eu trouxe essa ideia para o Java num port que chamei de nebulus-nabu: a mesma API, os mesmos CIDs, rodando sobre um nó Nabu embutido.

O que me levou a fazer o port foi uma necessidade bem concreta: validar a autenticidade de arquivos em massa, de forma automatizada, usando o CID como impressão digital. Se o CID de um arquivo muda, o conteúdo mudou, e uma modificação maliciosa aparece na hora. Para isso funcionar em escala dentro de uma aplicação Java, eu precisava calcular esses CIDs localmente, sem depender de um nó IPFS rodando e sem publicar nada.

O problema não é o CID. É misturá-lo com a rede

O IPFS junta duas ideias que, separadas, funcionam bem. A primeira é o armazenamento endereçado por conteúdo: o arquivo é fatiado, cada pedaço ganha um hash, os pedaços se organizam numa árvore (um DAG UnixFS) e a raiz dessa árvore é o CID. A segunda é uma rede peer-to-peer, com Bitswap e DHT, que descobre quem tem aquele CID e transfere os blocos.

Num nó típico, as duas acontecem juntas. Isso é razoável quando o objetivo é "colocar este arquivo no IPFS agora". Deixa de ser razoável em alguns casos bem comuns:

  • Você ainda está montando um site, um pacote ou uma coleção. Os arquivos já se apontam uns aos outros por CID, mas cada versão intermediária não deveria ir para a rede pública.
  • Você quer registrar ou compartilhar um CID primeiro — uma prova de que aquele conteúdo já existia — e só revelar o arquivo depois.
  • Você quer mandar o conteúdo por outro canal (um POST HTTP, um e-mail, um pendrive) e deixar que quem recebe confira o CID. A rede do IPFS, nesse caso, é opcional.
  • Você quer publicar uma vez, esperar um gateway público buscar uma cópia, e desligar o seu nó.

Em todos esses casos, o que você precisa primeiro é do endereço. A rede vem depois — ou, às vezes, não vem.

Um IPFS virtual: add offline, push quando você quiser

A analogia com o Git é a que o Nebulus usa, e é a que eu mantive. O add equivale a preparar o objeto e obter o identificador. O push é o que de fato fala com outros peers. O pull busca um CID que alguém já publicou. Enquanto você só adiciona e lê, não precisa de nó rodando.

No Java, a superfície é pequena. Nebulus implementa AutoCloseable. Escrita e leitura são síncronas. As chamadas de rede devolvem CompletableFuture:

try (Nebulus nebulus = new Nebulus()) {
    String cid = nebulus.add("Hello world".getBytes());  // calculado localmente, nada é publicado
    nebulus.push(cid).join();                           // agora está na rede pública do IPFS
}
Enter fullscreen mode Exit fullscreen mode

Essa é a API pública. Não há um método escondido que "já publica no add". Se você não chamar push, o conteúdo permanece só na pasta local.

O detalhe que torna isso útil de verdade — e não apenas uma pasta com hashes caseiros — é que esses CIDs são os mesmos do resto do IPFS. O importador do nebulus-nabu reproduz o que o Nebulus em JavaScript usa, e o que o Kubo gera com ipfs add --cid-version=1 --raw-leaves: CIDv1, folhas raw, pedaços de 256 KiB, DAG balanceado, sha2-256. A suíte de testes confere isso contra vetores de referência gerados com o importador JavaScript. "Hello world", por exemplo, é sempre:

bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e
Enter fullscreen mode Exit fullscreen mode

Você pode calcular esse CID no seu laptop, desconectado, e outra pessoa pode buscá-lo mais tarde com ipfs get ou com o pull do próprio Nebulus. O endereço não pertence à biblioteca. Pertence ao conteúdo.

Como isso funciona, por baixo da API

Tudo vive numa pasta, .nebulus por padrão. Buffers e downloads são gravados uma vez em src/, pelo sha256 do conteúdo. Cada CID vira uma entrada em ipfs/ — um link simbólico para o arquivo real, ou uma cópia, se os links não estiverem disponíveis. O estado do nó IPFS, quando existe, fica em repo/: o blockstore e a identidade do peer, que se mantém entre reinícios.

A decisão que sustenta a analogia com o Git está no add. Quando você adiciona um arquivo, o Nebulus não sobe o nó e não guarda os blocos do DAG no blockstore. Ele só calcula o CID e cria o ponteiro:

public String add(Path file) throws IOException {
    if (!Files.isRegularFile(file)) {
        throw new NoSuchFileException(file.toString(), null, "not a regular file");
    }
    ImportedNode node;
    try (InputStream in = Files.newInputStream(file)) {
        node = importer.importFile(in, BlockSink.HASH_ONLY);
    }
    String cid = node.cid().toString();
    storage.link(storage.resolve(cid), file);
    return cid;
}
Enter fullscreen mode Exit fullscreen mode

BlockSink.HASH_ONLY descarta os blocos depois de hasheá-los. O arquivo original nem é copiado: ipfs/<cid> aponta para ele onde está. (Se você mover ou apagar o arquivo, o link quebra; nesse caso, basta adicionar de novo. Buffers e downloads, esses sim, são copiados para src/.)

A rede aparece só no push. Aí o arquivo é relido, o importador emite os blocos para o nó, o CID é anunciado na DHT, e — por padrão — o push só termina quando um gateway público, o ipfs.io, passa a servir o conteúdo:

BlockSink sink = net::put;
try (InputStream in = Files.newInputStream(local)) {
    node = importer.importFile(in, sink);
}
net.provide(root);
if (options.verifyOnGateway()) {
    // espera o gateway responder 2xx para cada caminho publicado
}
Enter fullscreen mode Exit fullscreen mode

O pull faz o caminho inverso: busca os blocos, confere cada um contra o seu CID, reconstitui o arquivo em src/ e cria a entrada em ipfs/. Quem não chamou connect() antes não precisa se preocupar: push e pull sobem o nó sozinhos, na primeira vez.

O nó em si é um Nabu embutido (Bitswap, DHT Kademlia, blockstore em arquivo), atrás de uma interface pequena, IpfsNetwork. Isso permite testar push e pull numa rede só em memória, ou ligar dois nós na sua máquina sem tocar a rede pública. A API que você chama é a mesma.

Pastas também são offline. Você monta um mapa de nome para CID — CIDs que já estão no Nebulus — e recebe o CID da pasta:

try (Nebulus nebulus = new Nebulus(NebulusOptions.builder()
        .path("storage")
        .build())) {

    String hello = nebulus.add("hello world".getBytes(StandardCharsets.UTF_8));
    Path note = Files.writeString(Path.of("storage", "note.txt"), "ainda é um rascunho");
    String noteCid = nebulus.add(note);

    String folder = nebulus.folder(Map.of(
            "hello.txt", hello,
            "note.txt", noteCid));

    List<String> nomes = nebulus.list(folder);
    String texto = nebulus.get(folder + "/note.txt", StandardCharsets.UTF_8);
}
Enter fullscreen mode Exit fullscreen mode

Enquanto você não chama push(folder), essa pasta existe só no disco. Os links entre os arquivos já são CIDs reais. Você pode refazer a pasta, gerar outro CID, comparar, e publicar só a versão que interessa.

O que essa separação destrava

Rascunhos privados. Um site estático ou uma coleção em que cada peça aponta para as outras por CID é um grafo. Se cada add já publicasse, cada tentativa iria para a rede. Com o Nebulus, você monta o grafo localmente — add, folder, get, list — e escolhe o momento do push.

Prova de existência. O CID não revela o conteúdo, mas amarra um hash a ele. Você pode guardar, assinar ou registrar esse CID primeiro, e só depois revelar o arquivo. Quem receber o arquivo mais tarde recalcula o CID e confere. O endereço foi obtido offline; a revelação é um passo separado.

IPFS como pacote de dados. Como o CID é o mesmo do ecossistema, você pode enviar o arquivo por qualquer canal. Quem recebe não precisa confiar em você: confere o hash. A rede peer-to-peer é uma forma de distribuição, não a única, e não é pré-requisito para ter o endereço.

IPFS efêmero. Com as opções padrão, push termina quando o gateway já está servindo o conteúdo. A ideia é: uma vez que o ipfs.io (ou outro gateway que você configurar) buscou uma cópia, o seu nó pode parar de servir. É o oposto de deixar um daemon ligado para sempre. Se você não quiser esperar o gateway, verifyOnGateway(false) faz o push completar logo depois do anúncio na DHT — mas aí cabe a você manter o nó no ar até alguém buscar.

Nada disso exige uma API diferente para cada caso. São consequências de não publicar no add.

Limites e trocas, como o projeto está hoje

Vale ser direto sobre o que o port não faz, ou faz com ressalvas. Tudo abaixo está no repositório.

As pastas são planas, um nível, como no Nebulus original. Pastas aninhadas e diretórios fragmentados (HAMT) são rejeitados. Se o seu caso precisa de árvore profunda, esta biblioteca ainda não é o caminho.

No pull, só blocos sha2-256 são verificados contra o CID. Blocos com outras funções de hash são aceitos como chegam. No fluxo normal isso não aparece — os CIDs que o Nebulus gera são sha2-256 — mas é uma fronteira se você puxar conteúdo de outras ferramentas.

Com as opções padrão, o push espera o gateway. Atrás de NAT isso pode levar minutos, ou terminar com TimeoutException se nenhum peer alcançar o seu nó. O guia do projeto sugere redirecionar a porta do swarm, rodar numa máquina com IP público, ou desligar a verificação no gateway e manter o nó ligado. A porta padrão de escuta é 4002, de propósito, para não colidir com um Kubo local em 4001. Cada instância na mesma máquina precisa da sua própria porta e da sua própria pasta.

O add(Path) não copia o arquivo. É barato e deixa o conteúdo no lugar, mas o CID local depende do arquivo continuar onde está — a menos que você peça cópias com symbolicLinks(false), ou que o sistema recuse links (no Windows, sem o modo de desenvolvedor, o Nebulus passa a copiar e avisa uma vez).

Uma diferença consciente em relação ao JavaScript: o push de uma pasta publica o CID da própria pasta. O original copiava cada arquivo para a raiz MFS do nó e verificava o gateway sob o CID dessa raiz. Se você vem do Nebulus em JS, esse comportamento não é equivalente.

Também não prometo números de desempenho neste texto. O repositório não traz benchmarks, e eu prefiro não inventar.

Como experimentar

Você precisa de Java 17 ou mais recente. A escrita e a leitura offline não pedem um daemon do IPFS, nem acesso à rede. O trecho da pasta, acima, já é um programa completo: cria a pasta de armazenamento, calcula CIDs, monta um diretório e lê de volta.

O código está no GitHub: pedropietro/nebulus-nabu. O Quick Start leva você do zero ao primeiro CID.

As builds saem pelo JitPack. No Maven:

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.pedropietro</groupId>
    <artifactId>nebulus-nabu</artifactId>
    <version>main-SNAPSHOT</version>
  </dependency>
</dependencies>
Enter fullscreen mode Exit fullscreen mode

No Gradle:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}
dependencies {
    implementation 'com.github.pedropietro:nebulus-nabu:main-SNAPSHOT'
}
Enter fullscreen mode Exit fullscreen mode

Para ir além do offline, o guia do projeto traz dois programas a mais: um liga Alice e Bob na sua máquina, com bootstrap vazio, e nada sai do localhost; o outro publica na rede pública e espera o ipfs.io. No segundo caso, use um conteúdo novo e um pushTimeout folgado — ser encontrado atrás de NAT não é instantâneo.

Se você já trabalha com o Nebulus em JavaScript, a API é propositalmente familiar: add, download, folder, get, stream, connect, disconnect, push, pull, e eventos push/pull (os nomes originais, upload e download, também disparam). A diferença de idioma é a óbvia: no Java, rede é CompletableFuture, e as opções passam por um builder, NebulusOptions.

Separar não é complicar. É deixar cada passo no seu lugar

Eu não quis reinventar o IPFS. Quis um jeito, em Java, de usar o endereçamento de conteúdo sem levar a rede no mesmo gesto. O CID continua sendo o CID de todo mundo. O que muda é o momento em que ele deixa o seu disco.

Se você precisa de um hash interoperável agora e de uma decisão de publicação depois — um rascunho, uma prova, um pacote, uma publicação curta — essa separação é o desenho. O resto da API cabe numa classe só. O push continua lá, quando você quiser usá-lo.

Top comments (0)