Crate solid_pod_rs_forge 

solid-pod-rs-forge

A clean-room Rust reimplementation of the JavaScriptSolidServer forge plugin — a zero-build, server-rendered Git forge (a Gogs/Gitea slice) composed almost entirely from primitives solid-pod-rs already ships: git smart-HTTP (solid_pod_rs_git), write-as-commit provenance and Bitcoin anchoring (solid_pod_rs::provenance, solid_pod_rs::mrc20), NIP-98 auth (solid_pod_rs::auth::nip98), did:nostr identity (solid_pod_rs::did_nostr_types), and WAC gating (enforced by the embedding server before ForgeService::handle is reached).

IP posture

Everything here is derived from the forge plugin’s published behaviour and expressed as fresh Rust on solid-pod-rs’s own primitives. JSS is cited by function/section name only — no upstream JavaScript is transcribed. This mirrors how solid_pod_rs::bitcoin_tx and solid_pod_rs::auth::nip98 cite JSS while carrying an independent implementation.

Architecture rule — “words in pods, metadata in the forge”

Issue/PR/comment bodies live in the author’s own pod (WAC-governed, author-owned); the forge keeps only a spine index of pointers. Bodies are re-fetched at read time, bounded. Podless did:nostr agents store bodies in forge-hosted storage instead.

Native-only

The forge shells to git/git-http-backend, touches the filesystem, and runs a loopback HTTP client. It is never part of a core/wasm build and adds zero dependencies to the core crate.

Entry point

The crate is framework-agnostic: ForgeService::handle consumes a ForgeRequest and produces a ForgeResponse; the embedding server (actix/axum/hyper) translates its native types at the edge and WAC-gates the forge scope before dispatch — exactly as the server’s handle_git gates before invoking solid_pod_rs_git::GitHttpService.

Re-exports

pub use bodies::HostedReader;

pub use bodies::LoopbackFetch;

pub use config::ForgeConfig;

pub use error::ForgeError;

pub use hosted::HostedStore;

pub use ownership::ForgeAgent;

pub use request::esc;

pub use request::ForgeRequest;

pub use request::ForgeResponse;

pub use router::parse_route;

pub use router::Route;

pub use spine::FsSpineStore;

pub use spine::SpineStore;

pub use token::TokenError;

Modules

api

The JSON API read surface and repo metadata edit.

api_issues

The issues JSON API: list, thread, create, comment, close / reopen, retitle and label assignment.

auth

Caller-identity resolution for forge requests.

bodies

Two-phase pod-write coordinator.

compare

Compare: resolve a base and a (possibly cross-fork) head, then report ahead/behind counts, the commit list and a structured diff.

config

Forge configuration and the chain/mainnet policy guard.

config_file

JSON configuration layering: explicit config over a FORGE_CONFIG file.

diff

Structured unified-diff parser: one parse feeds the JSON API’s files[] -> hunks[] -> lines[] shape (and, later, the compare and pull request views).

error

Typed error enum with HTTP status mapping, mirroring the shape of solid_pod_rs_git::error::GitError.

forks

Forks: git clone --local --bare into the caller’s namespace, lineage in the fork’s own git config, bounded fork counts, and the hidden refs/forge/* namespace.

gitmark

Repo-held git-mark trails and the NIP-34 anchor tags they feed.

gitrun

Argv-only, hardened git runner for the read features (JSON API, search, releases, archive).

guard

Request-path guards: the percent-encoding refusal and the owner / repo / ref / path validators the JSON API and the HTML lanes share.

hosted

Forge-hosted body storage for podless did:nostr agents.

hosted_edit

<prefix>/api/hosted/<hex>/<uuid>: a podless agent’s words, hosted by the forge.

html

Server-rendered HTML views — zero framework, inline CSS, every interpolation passed through crate::request::esc.

labels

Issue (and pull request) labels: GitHub’s default set, owner-only CRUD, per-item assignment, list filtering, rename / delete cascades and the luminance-aware chip helpers.

locks

Per-repository serialisation locks for spine writes.

markdown

A small, bounded, escape-first Markdown renderer.

merge

Real merges of pull requests: git merge-tree --write-tree, fast-forward when possible, otherwise a two-parent commit, a compare-and-swap ref update, and the git version gate.

ownership

Caller identity + repository-owner resolution and the namespace-write guard.

prelude

Convenience import surface.

preview

POST <prefix>/api/repos/<owner>/<repo>/preview: the unstaged tier.

pulls

Pull requests: the pulls spine index, the JSON API and the server-rendered pages.

releases

Releases (every tag, newest first) and git archive downloads.

repo

Repository materialisation and filesystem layout.

request

Binder-agnostic request/response types plus the XSS-neutralisation spine.

router

Pure route dispatch — maps (method, path) to a Route.

search

In-repo code search: a bounded, unindexed git grep over the default branch, plus path-name matches.

spine

The spine — the forge’s only durable non-git metadata.

token

Forge push token — a macaroon-lite HMAC bearer.

web_edit

POST <prefix>/api/repos/<owner>/<repo>/edit: commit one file over HTTP, the GitHub web-editor equivalent.

xlogin

The vendored xlogin.js login widget route and the page Content Security Policy.

Structs

ForgeService

The forge service. One instance is built at server startup and shared (Arc) across requests. All durable state lives under plugin_dir.

Constants

WIDGET_PAGE_HEADER

Internal response header a handler sets to mark a page that loads the vendored login widget, so ForgeService::handle gives it the widget Content-Security-Policy. It never reaches the client.