.gitbay/wiki/Architecture/02-Components.org
93 lines · 6840 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/deps= | Dependency manifest parsing and registry checks (opt-in per repository). |
39| =internal/config= | Configuration load and validation. |
40| =internal/web= | Embedded templates, stylesheet and fonts. |
41| =internal/protocol= | Exit codes, JSON envelope, argv tokenizer. |
42
43* The command registry
44
45Every capability is a =Command= (=internal/control/control.go=):
46
47| Field | Meaning |
48|--------------+---------------------------------------------------------------------|
49| =Path= | noun and verb, e.g. =keys add= |
50| =Flags= | parsed by one parser for every command (=internal/control/flags.go=)|
51| =ReadsStdin= | the only way a handler receives stdin; otherwise stdin is emptied |
52| =ReadOnly= | safe for read-scoped tokens and =GET /api/v1/read=; tested to write nothing |
53| =Run= | the handler |
54
55Every surface builds a =Ctx= and calls =Dispatch=
56(=internal/control/control.go=):
57
58| Surface | =Ctx.Source= | =Ctx.Scope= | =Ctx.ReadOnly= | Code |
59|--------------+-------------------+------------------------+---------------------+-----------------------------------|
60| SSH | key fingerprint | the key's scope | false | =internal/sshd/sshd.go= (=Exec=) |
61| Web | =web= | =full= | false | =internal/httpd/control.go= |
62| JSON API | =api= | =full= | token scope = read | =internal/httpd/api.go=, =apiread.go= |
63| Host (root) | =host= | =full= | false | =cmd/gitbayd= admin subcommands |
64
65=Dispatch= applies, in order: =--term= and =--json= stripping; the scope
66gate; the read-only gate; the disabled-account gate; the =admin= noun
67gate; the pending-account gate; the per-account write budget; stdin
68gating; the handler; and an audit row for every successful mutating
69command. Details in [[file:05-Identity-and-Access.org][5. Identity and access]].
70
71* Background workers
72
73Started by =gitbayd serve= (=cmd/gitbayd/main.go=):
74
75| Worker | Starts when | Trigger | Queue / table |
76|-----------------------+-----------------------------+---------------------------------+-----------------------|
77| Webhook delivery | always | 2 s poll | =webhook_deliveries= |
78| Mail | =mail.smtp_host= set | 2 s poll | =notifications= |
79| APNs push | =push.enabled= | 2 s poll | =push_queue= |
80| Mirrors | always | 10 s tick, per-mirror interval | =mirrors= |
81| CI scheduler | always | 1 min tick; reaps stale builds | =build_schedules=, =builds= |
82| Dependency checks | always (repos opt in) | =deps.check_interval_hours= | =dep_checks= |
83| Retention sweep | always | hourly | sessions, tokens, retained tables |
84| Pending-account reaper| =registration.pending_expiry= set | hourly | =users= |
85
86* Git hooks
87
88Repositories carry generated hook scripts (mode 0755, regenerated at
89startup, =internal/hookd/hookd.go=) that run
90=gitbayd hook pre-receive|post-receive=. The hook process connects to
91the daemon's Unix socket (=<root>/hook.sock=, =hookd.go=) and asks
92for a decision; the daemon holds the policy. See
93[[file:04-Trust-Boundaries.org][4. Trust boundaries]], flow B.