From 6a78d0ab5324bf1caf7d7f2b79a8eb2b62921933 Mon Sep 17 00:00:00 2001
From: Runxi Yu <me@runxiyu.org>
Date: Sat, 5 Apr 2025 15:07:03 +0800
Subject: Update forge docs

---
 content/forge/internals/_index.md | 32 +++++++++++++++++++++++++++++++
 content/forge/internals/hookc.md  | 40 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 content/forge/internals/_index.md
 create mode 100644 content/forge/internals/hookc.md

(limited to 'content/forge/internals')

diff --git a/content/forge/internals/_index.md b/content/forge/internals/_index.md
new file mode 100644
index 0000000..9d00291
--- /dev/null
+++ b/content/forge/internals/_index.md
@@ -0,0 +1,32 @@
+---
+title: Internals
+---
+
+This section describes some of the internals of the forge.
+
+It is not intended for end users or even system administrators, but only for
+developers.
+
+## Architecture
+
+The **main forge daemon** handles HTTP requests, SSH connections, incoming
+emails, IMAP access, the API, and just about anything that the user might
+want to access. It connects to the PostgreSQL database for most of its data,
+with the exception of Git repositories.
+
+The **git2d** daemon is a separate process that handles all Git operations.
+Currently, the forge daemon automatically deploys and starts this daemon
+when it is started, and connects via UNIX domain sockets.
+Note that git2d is currently incomplete, so the forge daemon uses go-git for
+many operations.
+
+Additionally, the main forge daemon currently launches instances of
+git-receivv-pack and git-upload-pack for Git network operations. This will be
+merged into git2d in the future.
+
+In the future Git operations may be delegated to multiple nodes by using TCP
+instead of UNIX domain sockets and by ensuring all Git operations happen
+through git2d.
+
+In the current architecture, git-receive-pack launches a pre-receive hook,
+[hookc](hookc/).
diff --git a/content/forge/internals/hookc.md b/content/forge/internals/hookc.md
new file mode 100644
index 0000000..3c270fc
--- /dev/null
+++ b/content/forge/internals/hookc.md
@@ -0,0 +1,40 @@
+---
+title: hookc
+---
+
+`hookc` is a helper binary for Git server-side hooks that relays the hook's
+context to a persistent daemon via a UNIX domain socket and communicates back
+any relevant responses.
+
+It is intended to be invoked by `git-receive-pack` for hooks such as
+`pre-receive`, `update`, and `post-receive`.
+
+## Environment variables
+
+- `LINDENII_FORGE_HOOKS_SOCKET_PATH`:
+  Absolute path to the UNIX domain socket on which the daemon is listening.
+- `LINDENII_FORGE_HOOKS_COOKIE`:
+  64-character authentication cookie used to validate the hook client to the
+  daemon.
+
+## Operation
+
+lindenii-forge-hookc collects the following information and sends it to
+the daemon:
+
+- All command-line arguments
+- All `GIT_*` environment variables
+- The raw hook stdin (e.g., old/new ref triplets for pre-receive)
+
+After sending this data, it waits for a one-byte status code from the daemon,
+which becomes `hookc`'s own exit status.
+
+If the daemon sends any output afterward, it is forwarded to standard error and
+will appear as `remote:` output to the user.
+
+## Known issues
+
+- The status byte from the daemon currently must be sent before any
+  stderr output.
+- Currently assumes stdin and stderr are pipes, which is not guaranteed
+  in future versions of Git.
-- 
cgit v1.2.3