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