All 22 apps

CandyGitServer

Git server: smart-HTTP clone/fetch/push/LFS live

inspired by charmbracelet/soft-serve gitserversshself-hosted

CandyGitServer code coverage

Status: smart-HTTP transport live. serve --http runs a real git clone, git fetch and authenticated git push over smart HTTP, plus the LFS batch and object routes — a shared pkt-line codec plus git's own --stateless-rpc engine, e2e-tested against the system git binary — the launched serve --http process itself is driven over a live socket — behind fail-closed access gates. The SSH ForceCommand dispatcher and the git-daemon advertisement exist at class level; the sshd host recipe and a fetch-completing daemon are open work. See the README "Known gaps" inventory.

Install

composer require sugarcraft/candy-git-server

Quickstart

use SugarCraft\GitServer\{AccessControl, Config, Repo, User};
use SugarCraft\GitServer\Git\GitDaemon;

$config = Config::fromDefaults();        // CANDY_GIT_SERVER_DATA_PATH env var, else defaults
                                         // (Config::load($yamlPath) reads a config file)

// Describe a repository and create it as a bare git repo on disk
$repo = Repo::new('my-project', $config->reposPath() . '/my-project.git')
    ->withDescription('Greeting service')
    ->withPublic(true)
    ->addCollaborator('alice')
    ->init();

// Ask the permission matrix
$acl = AccessControl::instance();
$acl->canWrite(User::new('alice'), $repo);   // true  (collaborator)
$acl->canWrite(User::new('bob'), $repo);     // false
$acl->canRead(null, $repo);                  // false (anonymous reads are opt-in:
$acl->setAllowAnonymousRead(true);        //   git.allow_anonymous_read in config)

// Library surface (not assembled): a future host would drive the daemon
// like this — the serve() method exists; no shipped entrypoint calls it.
$daemon = new GitDaemon($config);
$daemon->registerRepo($repo);

What's in the box

SSH front end (class)SSHServer authenticates users by public key and dispatches git upload-pack / receive-pack for the single request a host sshd ForceCommand hands it. No SSH wire protocol, no shipped entrypoint.
Git daemon (class)GitDaemon answers the git:// git-upload-pack advertisement via a real git upload-pack --advertise-refs child — read-only by design, pushes refused at dispatch; completing fetches over git:// is open work (see README Known gaps) and nothing constructs it yet.
Smart-HTTP transportHttpSmartProtocol\Server + HttpListener serve git clone, git fetch and authenticated git push behind serve --http; identity resolution and access gates answer before a git child is spawned or a response byte written (the router reads size-bounded request bodies before dispatching them), hook declines ride in-band, and the LFS batch + object routes share the router with validated oids, sizes and atomic storage. Identity arrives via HTTP Basic or the paired X-CandyGitServer-User + X-CandyGitServer-User-Sig token headers.
Access controlAccessControl answers read / write / admin for a user (or anonymous) against a repo's visibility and collaborators.
LFS supportGit LFS over HTTP through LFSHandler and a pluggable storage backend.
Config fileYAML server configuration via Config::load(), or env + defaults via Config::fromDefaults().

Source & demos

Try the quickstart →

API

ClassMethodDescription
Configstatic fromDefaults() / static load(path)Configuration from env + defaults, or from a YAML file
ConfigreposPath() / sshPath() / lfsPath()Data directories
Repostatic new(name, path) / withDescription() / withPublic() / withPrivate() / withVisibility() / withAllowPush() / addCollaborator()Immutable repository description
Repoinit() / path() / branches()Create the bare repository; inspect it
Userstatic new(username) / withAdmin() / withPasswordHash() / withAuthorizedKeys() / addAuthorizedKey()Immutable account: hashed password + SSH keys (accounts persist via UserStore)
AccessControlstatic instance() / canRead() / canWrite() / canAdmin()Permission checks
SSHServer__construct(Config) / registerUser() / registerRepo() / handleConnection(stream, username, command, ?publicKey = null)SSH command dispatcher
GitDaemon__construct(Config) / registerRepo() / registerRepos() / serve(pidFile = '') / serveAsync(?loop, pidFile = '') / shutdown()git:// advertisement daemon (read-only)
HttpSmartProtocol\Server__construct(Config) / registerRepo() / registerUser() / handleRequest(…)Smart-HTTP router: clone, fetch, auth-gated push, LFS
Git\PktLinestatic encode(payload) / static flush() / static decode(bytes) / static isServiceHeader(payload, service)Shared pkt-line codec (4-hex length prefix)
Git\StatelessRpcstatic advertise(service, repoPath, ?deadlineSeconds = null) / static negotiate(service, repoPath, body, maxBytes, ?deadlineSeconds = null)git --stateless-rpc children: capped drain, TERM-to-KILL reap
HttpSmartProtocol\HttpListener__construct(Server, host, port, ?loop) / start() / stop() / listenAddress()Smart-HTTP socket listener behind serve --http