.gitbay/wiki/Architecture/02-Components.org
95 lines · 7156 bytes
1#+title: Components
2
3[[file:diagrams/02-components.svg]]
4
5* Binaries
6
7| Binary | Role | Entry |
8|-----------------+----------------------------------------------------------------------+-------------------------------|
9| =gitbayd= | daemon: listeners, workers, git hooks, admin and maintenance | =cmd/gitbayd/main.go= |
10| =gitbay= | end-user CLI; a thin client that runs control commands over SSH | =cmd/gitbay/main.go=, =ssh.go= |
11| =gitbay-runner= | CI runner; claims builds over SSH and runs them, normally in podman | =cmd/gitbay-runner/main.go= |
12
13=gitbayd= subcommands: =serve=, =check-config=, =migrate=, =admin=,
14=authorized-keys= and =shell= (for =ssh.mode = system=), =version=, and
15the hidden =hook= used by git (=cmd/gitbayd/main.go=,
16=cmd/gitbayd/hook.go=).
17
18* Packages
19
20| Package | Responsibility |
21|----------------------+--------------------------------------------------------------------------------|
22| =internal/control= | The command registry and every handler. The only place business rules live. |
23| =internal/policy= | Access predicates (=CanRead/CanWrite/CanAdmin=), key scopes, push rules, CODEOWNERS, reserved names. |
24| =internal/store= | SQLite access, hand-written SQL, migrations (=internal/store/migrations/=). |
25| =internal/sshd= | SSH listener, public-key auth, session exec, dispatch to git transport or registry, LFS bridge. |
26| =internal/httpd= | HTTPS: web UI, smart HTTP (fetch only), LFS HTTP, JSON API, login, security headers. |
27| =internal/hookd= | Unix-socket server answering git's pre-receive and post-receive hooks. |
28| =internal/gitutil= | Subprocess wrappers around =git=. No git library is linked. |
29| =internal/sig= | Verification of OpenPGP and SSHSIG commit and tag signatures. Verification only. |
30| =internal/gitd= | Anonymous =git://= daemon, upload-pack only, off by default. |
31| =internal/ci= | =.gitbay/ci.yml= parsing, cron schedules, the scheduler and stale-build reaper. |
32| =internal/lfs= | Content-addressed LFS store and HMAC transfer tokens. |
33| =internal/webhook= | Outbound webhook delivery with SSRF checks, HMAC signing, retries. |
34| =internal/mirror= | Push and pull mirror worker. |
35| =internal/gitpin= | Resolves and checks a user-supplied http(s) remote and pins git to the checked addresses; mirror sync and =repo import=. |
36| =internal/notify=, =internal/mail= | Mail queue drain and SMTP. |
37| =internal/push= | APNs queue drain and provider-token signing. |
38| =internal/mailin=, =internal/imapc=, =internal/mailreply= | Reply by mail: the IMAP client, the reply token, and the processor that posts a reply through =issue comment= / =mr comment=. |
39| =internal/deps= | Dependency manifest parsing and registry checks (opt-in per repository). |
40| =internal/config= | Configuration load and validation. |
41| =internal/web= | Embedded templates, stylesheet and fonts. |
42| =internal/protocol= | Exit codes, JSON envelope, argv tokenizer. |
43
44* The command registry
45
46Every capability is a =Command= (=internal/control/control.go=):
47
48| Field | Meaning |
49|--------------+---------------------------------------------------------------------|
50| =Path= | noun and verb, e.g. =keys add= |
51| =Flags= | parsed by one parser for every command (=internal/control/flags.go=)|
52| =ReadsStdin= | the only way a handler receives stdin; otherwise stdin is emptied |
53| =ReadOnly= | safe for read-scoped tokens and =GET /api/v1/read=; tested to write nothing |
54| =Run= | the handler |
55
56Every surface builds a =Ctx= and calls =Dispatch=
57(=internal/control/control.go=):
58
59| Surface | =Ctx.Source= | =Ctx.Scope= | =Ctx.ReadOnly= | Code |
60|--------------+-------------------+------------------------+---------------------+-----------------------------------|
61| SSH | key fingerprint | the key's scope | false | =internal/sshd/sshd.go= (=Exec=) |
62| Web | =web= | =full= | false | =internal/httpd/control.go= |
63| JSON API | =api= | =full= | token scope = read | =internal/httpd/api.go=, =apiread.go= |
64| Host (root) | =host= | =full= | false | =cmd/gitbayd= admin subcommands |
65
66=Dispatch= applies, in order: =--term= and =--json= stripping; the scope
67gate; the read-only gate; the disabled-account gate; the =admin= noun
68gate; the pending-account gate; the per-account write budget; stdin
69gating; the handler; and an audit row for every successful mutating
70command. Details in [[file:05-Identity-and-Access.org][5. Identity and access]].
71
72* Background workers
73
74Started by =gitbayd serve= (=cmd/gitbayd/main.go=):
75
76| Worker | Starts when | Trigger | Queue / table |
77|-----------------------+-----------------------------+---------------------------------+-----------------------|
78| Webhook delivery | always | 2 s poll | =webhook_deliveries= |
79| Mail | =mail.smtp_host= set | 2 s poll | =notifications= |
80| APNs push | =push.enabled= | 2 s poll | =push_queue= |
81| Mail replies | =mail.inbound.enabled= | =mail.inbound.poll_interval= (1 min) | IMAP mailbox, =mail_replies= |
82| Mirrors | always | 10 s tick, per-mirror interval | =mirrors= |
83| CI scheduler | always | 1 min tick; reaps stale builds | =build_schedules=, =builds= |
84| Dependency checks | always (repos opt in) | =deps.check_interval_hours= | =dep_checks= |
85| Retention sweep | always | hourly | sessions, tokens, retained tables |
86| Pending-account reaper| =registration.pending_expiry= set | hourly | =users= |
87
88* Git hooks
89
90Repositories carry generated hook scripts (mode 0755, regenerated at
91startup, =internal/hookd/hookd.go=) that run
92=gitbayd hook pre-receive|post-receive=. The hook process connects to
93the daemon's Unix socket (=<root>/hook.sock=, =hookd.go=) and asks
94for a decision; the daemon holds the policy. See
95[[file:04-Trust-Boundaries.org][4. Trust boundaries]], flow B.