docs: composability boundary + public-clone deployment anchor
- vision: 'ALPN as a service' section (core is front-door-blind; v1 reduces to storage + ACL + protocol adapters); primary deployment target = public anonymous fetch, authenticated push, minimal ACL - alk-stack: concrete composability boundary (core+transport depend on alkcall types only; adapters replaceable) - AGENTS.md: convention 15 codifies the boundary Verified: none needed (markdown only)
This commit is contained in:
1 parent
1df339f4ec
commit
4d3ec3cc63
3 files changed
+62
-2
No files matched your search
+37
-1
@@ -45,7 +45,8 @@ is designed from day one, not retrofitted.
|
||||
3. **No plaintext secrets at rest** — alkvault or nothing.
|
||||
4. **Thin interfaces, one core** — http and ssh are adapters that authenticate,
|
||||
resolve a repo, and hand a duplex stream to the transport layer. Policy
|
||||
lives in exactly one place.
|
||||
lives in exactly one place. The core never knows which front door is
|
||||
talking (see "ALPN as a service" below).
|
||||
5. **Honest capability advertisement** — the git protocol advertises only
|
||||
what we actually serve (this is both protocol correctness and the
|
||||
security pattern: promise/enforce in the same place).
|
||||
@@ -75,6 +76,41 @@ is designed from day one, not retrofitted.
|
||||
| `alkgit-ssh` | ssh front door (git commands over alkcall channels) |
|
||||
| `alkgitd` | binary: config, assembly, TLS/ACME, serving loops |
|
||||
|
||||
## Composability: "ALPN as a service"
|
||||
|
||||
alkgit is the git member of the alk "ALPN as a service" family — alktty,
|
||||
alktunnels, and alksocks (socks5) follow the same pattern, and the alknet
|
||||
mono-repo is being decomposed into exactly these pieces for rewrite. The
|
||||
pattern's load-bearing rule: **`alkgit-core` + `alkgit-transport` never know
|
||||
which front door is talking.** The transport layer consumes (identity, repo
|
||||
id, duplex stream, limits) and speaks git; everything above the stream is
|
||||
the adapter's problem. That is what keeps alkgit composable for downstream
|
||||
use:
|
||||
|
||||
- A future gitea/gitlab-like application should be able to embed
|
||||
`alkgit-core` + `alkgit-transport` (or talk to `alkgitd`) and add its own
|
||||
UI/issues/PR layer without forking anything here.
|
||||
- The admin API is a set of alkcall ops, not an embedded web framework —
|
||||
a downstream app can either use it or replace it.
|
||||
- Nothing in the core may reach upward into alkhttp/alkssh concerns
|
||||
(no http types, no channel types below the transport boundary).
|
||||
|
||||
The v1 reduction follows from this: **storage + ACL + protocol adapters**.
|
||||
A simple static/template web UI for the public repo listing is explicitly
|
||||
out of scope here (would be a separate downstream thing on top).
|
||||
|
||||
## Primary deployment target
|
||||
|
||||
Our own use case is the design anchor: **public self-hosted repos with
|
||||
anonymous clone over http, authenticated push, no gitea-style app features
|
||||
in use**. So:
|
||||
|
||||
- Anonymous *fetch* (clone/fetch advertisement + pack) on explicitly-public
|
||||
repos is a first-class path, not an afterthought.
|
||||
- Push is always authenticated, on every repo, no exceptions.
|
||||
- ACL must be simple enough to reason about completely: repo visibility
|
||||
(public/private) + identity-based read/write, nothing richer in v1.
|
||||
|
||||
## What phase 0 must still produce before phase 1
|
||||
|
||||
- [x] gitoxide capability + version research (`gitoxide.md`)
|
||||
|
||||
Reference in new issue
Block a user