CandyGitServer
Git server: smart-HTTP clone/fetch/push/LFS live
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 transport
HttpSmartProtocol\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 control
AccessControl 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
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by charmbracelet/soft-serve (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Config | static fromDefaults() / static load(path) | Configuration from env + defaults, or from a YAML file |
| Config | reposPath() / sshPath() / lfsPath() | Data directories |
| Repo | static new(name, path) / withDescription() / withPublic() / withPrivate() / withVisibility() / withAllowPush() / addCollaborator() | Immutable repository description |
| Repo | init() / path() / branches() | Create the bare repository; inspect it |
| User | static new(username) / withAdmin() / withPasswordHash() / withAuthorizedKeys() / addAuthorizedKey() | Immutable account: hashed password + SSH keys (accounts persist via UserStore) |
| AccessControl | static 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\PktLine | static encode(payload) / static flush() / static decode(bytes) / static isServiceHeader(payload, service) | Shared pkt-line codec (4-hex length prefix) |
| Git\StatelessRpc | static 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 |