Mercurial

annotate hg-web/README.md @ 252:7a7581f040e8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ui] Add scoped notification component Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Tue, 04 Aug 2026 11:57:16 -0700
parents c5129452493e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 # hg-web
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
3 A custom Mercurial forge and repository browser. The application keeps the
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
4 networking and HTTP stack in C with Seobeo, while the hand-drawn web interface
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
5 is implemented in React and TypeScript.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
6
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
7 ## Wiki tree
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
9 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
10 hg-web
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
11 ├── Runtime
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
12 │ ├── hg_web_server :6970
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
13 │ │ ├── React application and static assets
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
14 │ │ ├── repository browsing API
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
15 │ │ ├── commit graph API
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
16 │ │ └── Mercurial wire-protocol proxy
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
17 │ └── hg serve :4444
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
18 │ ├── repository files and graph data
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
19 │ └── Mercurial pull/push protocol
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
20 ├── Backend
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
21 │ ├── main.c
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
22 │ └── ../seobeo
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
23 │ ├── s_network.c
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
24 │ ├── s_web.c
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
25 │ ├── s_http_client.c
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
26 │ └── s_ssl.c
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
27 ├── Frontend
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
28 │ └── src
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
29 │ ├── main.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
30 │ ├── components
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
31 │ │ ├── app.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
32 │ │ ├── directory-browser.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
33 │ │ ├── graph.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
34 │ │ ├── header.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
35 │ │ ├── footer.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
36 │ │ ├── theme.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
37 │ │ └── repo-browser.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
38 │ ├── index.html
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
39 │ ├── index.css
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
40 │ ├── base.css
224
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
41 │ └── custom pencil, panda, and icon assets
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
42 ├── Build
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
43 │ ├── BUILD
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
44 │ ├── ../gui_ze/gui_ze.bzl
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
45 │ ├── ../markdown_converter
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
46 │ └── ../third_party/highlight
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
47 └── Operations
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
48 └── deploy.sh
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
49 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
50
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
51 `repo-browser.tsx` is an older standalone browser implementation. The active
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
52 entry point is `main.tsx`, which renders `app.tsx`; `app.tsx` embeds
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
53 `directory-browser.tsx`.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
54
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
55 ## Runtime topology
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
57 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
58 Browser
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
59 |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
60 | HTTPS
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
61 v
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
62 nginx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
63 |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
64 | HTTP :6970
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
65 v
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
66 hg_web_server (main.c + Seobeo)
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
67 |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
68 | HTTP :4444
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
69 v
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
70 hg serve (Zenbu Mercurial repository)
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
71 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
72
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
73 The C server owns the public routes. It serves the application shell and
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
74 assets, translates browser API requests into `hg serve` requests, and streams
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
75 Mercurial wire-protocol traffic without routing bundle data through the normal
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
76 buffered HTTP response path.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
77
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
78 ## Request flows
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
79
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
80 ### Application shell
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
81
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
82 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
83 GET /, /directories, or /graph
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
84 -> GetReactHome
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
85 -> hg-web/src/index.html
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
86 -> /page.js
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
87 -> src/main.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
88 -> components/app.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
89 ```
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
91 ### Repository browser
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
92
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
93 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
94 directory-browser.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
95 -> GET /api/repo/list?path=...
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
96 -> ApiListDirectory
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
97 -> GET hg-serve/file/tip/<path>?style=json
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
98
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
99 file or README selection
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
100 -> GET /api/repo/file?path=...
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
101 -> ApiGetFile
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
102 -> GET hg-serve/raw-file/tip/<path>
224
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
103 -> highlight.js, markdown_converter WASM, or inline static preview
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
104 ```
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
105
224
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
106 Images, SVG, video, audio, and PDF files open in the forge preview modal.
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
107 Unknown binary files retain a download link. The raw file API supplies explicit
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
108 MIME types, `nosniff`, inline disposition for supported previews, and sandboxed
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
109 SVG responses.
3007ef5fc0ed [hg-web] Simplify visuals and preview static files
MrJuneJune <me@mrjunejune.com>
parents: 223
diff changeset
110
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
111 ### Commit graph
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
112
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
113 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
114 graph.tsx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
115 -> GET /api/graph/<revision>?graphtop=...&style=json
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
116 -> ApiGetGraph
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
117 -> GET hg-serve/graph/<revision>?...
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
118 -> React rows + custom pencil/panda canvas
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
119
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
120 graph row selection
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
121 -> /changeset/<revision>
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
122 -> GET /api/changeset/<revision>
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
123 -> ApiGetChangeset
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
124 -> GET hg-serve/json-rev/<revision>
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
125 -> changeset metadata + rendered diff
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
126 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
127
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
128 ### Mercurial clone, pull, and push
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
129
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
130 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
131 Mercurial client
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
132 -> GET or POST /repo
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
133 -> StreamHgWireProtocol
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
134 -> hg serve /?cmd=...
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
135 -> binary-safe streamed response
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
136 ```
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
137
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
138 ## Route map
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
139
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
140 | Method | Route | Owner | Purpose |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
141 | --- | --- | --- | --- |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
142 | `GET` | `/` | `GetReactHome` | Application shell |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
143 | `GET` | `/directories` | `GetReactHome` | Legacy application-shell route |
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
144 | `GET` | `/directory` | `GetReactHome` | Repository browser application route |
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
145 | `GET` | `/graph` | `GetReactHome` | Commit graph application route |
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
146 | `GET` | `/changeset/:changeset_id` | `GetReactHome` | Changeset application route |
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
147 | `GET` | `/api/repo/list` | `ApiListDirectory` | Directory listing JSON |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
148 | `GET` | `/api/repo/file` | `ApiGetFile` | Raw tracked file |
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
149 | `GET` | `/api/repo/readme` | `ApiGetReadme` | Directory README content |
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
150 | `GET` | `/api/graph/:graph_id` | `ApiGetGraph` | Mercurial graph JSON |
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
151 | `GET` | `/api/changeset/:changeset_id` | `ApiGetChangeset` | Changeset metadata and diff JSON |
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
152 | `GET`, `POST` | `/repo` | `StreamHgWireProtocol` | Mercurial wire protocol |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
153
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
154 ## Frontend ownership
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
155
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
156 | File | Responsibility |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
157 | --- | --- |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
158 | `src/components/app.tsx` | Client-side routes, landing page, tabs, and history |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
159 | `src/components/directory-browser.tsx` | Breadcrumbs, listings, prefetch, file modals, README rendering |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
160 | `src/components/graph.tsx` | Graph fetching, pagination, canvas edges, panda nodes |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
161 | `src/components/theme.tsx` | Stored light/dark preference and system-theme integration |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
162 | `src/components/header.tsx` | Forge identity and theme control |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
163 | `src/components/footer.tsx` | Shared footer |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
164 | `src/index.css`, `src/base.css` | Custom visual language and layout |
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
165
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
166 Keep the custom assets and visual language in this package. New forge screens
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
167 should reuse the existing CSS variables, typography, textures, and components
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
168 instead of introducing a generic design system.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
169
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
170 ## Build and local run
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
171
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
172 Build the server and deployable bundle from the repository root:
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
173
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
174 ```bash
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
175 bazel build //hg-web:hg_web_server
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
176 bazel build //hg-web:hg_web_server_bundle
223
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
177 bazel test //hg-web:tests
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
178 bazel test //markdown_converter/tests:markdown_to_html_test
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
179 bazel test //seobeo/tests:all
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
180 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
181
223
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
182 `//hg-web:tests` creates a temporary two-commit Mercurial repository and runs
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
183 the application in pinned Chromium through Playwright. It covers shell routes,
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
184 files and README rendering, graph and changeset navigation, browser history,
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
185 console and page errors, API validation, Mercurial wire protocol, Markdown
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
186 script escaping, static assets, and backend outages. The test invokes the
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
187 workspace Mercurial CLI with an isolated configuration and home directory.
0e7b9464248d [hg-web] Add browser route regression coverage
MrJuneJune <me@mrjunejune.com>
parents: 222
diff changeset
188
222
a8d6435dc021 [hg-web] Run local stack through Bazel
MrJuneJune <me@mrjunejune.com>
parents: 221
diff changeset
189 Build and run the complete local stack with one Bazel command:
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
190
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
191 ```bash
222
a8d6435dc021 [hg-web] Run local stack through Bazel
MrJuneJune <me@mrjunejune.com>
parents: 221
diff changeset
192 bazel run //hg-web:dev
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
193 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
194
222
a8d6435dc021 [hg-web] Run local stack through Bazel
MrJuneJune <me@mrjunejune.com>
parents: 221
diff changeset
195 This starts `hg serve` on `127.0.0.1:4444` and `hg_web_server` on port `6970`.
249
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
196 The `hg serve` process comes from `//third_party/mercurial:runtime` and points at
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
197 the current workspace. Stopping the Bazel target stops both child processes.
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
198
249
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
199 The bundle contains `hg_web_server`, `hg-web/run_hg_web`, a pinned pure-Python
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
200 Mercurial runtime, and `hg-web/src/`, including generated `page.js`, markdown
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
201 WASM, highlight.js, styles, and image assets.
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
202
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
203 ## Deployment contract
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
204
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
205 The expected production layout is:
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
206
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
207 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
208 nginx
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
209 -> hg_web_server.service
249
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
210 -> /opt/hg_web_server/active/hg-web/run_hg_web
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
211 -> bundled Mercurial 7.2.3 serves
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
212 /opt/hg_web_server/repository on 127.0.0.1:4444
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
213 -> hg_web_server serves the forge on 127.0.0.1:6970
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
214 ```
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
215
249
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
216 `deploy.sh` follows the same new/active bundle swap as the personal site. It
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
217 builds the optimized bundle and maintains a canonical repository outside the
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
218 release directories. The first deploy creates it with a locking-aware local
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
219 clone. Later deploys create a Mercurial bundle from the workspace and pull that
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
220 bundle into the persistent repository, preserving any commits pushed directly
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
221 to production. The script verifies the repository, installs the systemd unit,
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
222 swaps the active directory, restarts the combined service, and checks
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
223 `http://127.0.0.1:6970/`. A failed restart restores the previous active
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
224 directory.
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
225
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
226 There is no separate production `hg serve` service and no dependency on the
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
227 host's `hg` command. The pinned Mercurial wheel requires CPython 3.11. The
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
228 systemd unit uses `KillMode=control-group`, so both the Mercurial and C child
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
229 processes stop together.
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
230
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
231 On its first run, deploy also installs `/etc/nginx/sites-available/hg-web` when
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
232 Nginx uses Debian-style `sites-available`/`sites-enabled` directories. Existing
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
233 site files are left untouched.
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
234
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
235 ```bash
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
236 NGINX_SERVER_NAME=zenbu.babocoder.com bazel run //hg-web:deploy
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
237 ```
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
238
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
239 The checked-in template listens on origin HTTP port 80, which works when TLS is
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
240 terminated upstream. For direct origin TLS, provide a complete certificate-aware
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
241 template:
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
242
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
243 ```bash
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
244 NGINX_SITE_TEMPLATE=/etc/nginx/templates/hg-web-tls.conf \
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
245 bazel run //hg-web:deploy
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
246 ```
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
247
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
248 Set `MANAGE_NGINX=false` to leave Nginx untouched. `NGINX_SITE_NAME`,
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
249 `NGINX_SITE_AVAILABLE`, and `NGINX_SITE_ENABLED` can override the destination
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
250 names and paths. `DEPLOY_ROOT` controls the validated deployment root;
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
251 `REPOSITORY_PATH` can override the persistent canonical repository within it.
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
252
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
253 Pushes are disabled by default. `HG_ALLOW_PUSH=true` enables unauthenticated
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
254 pushes in the internal `hg serve`; only use it when `/repo` is protected by
c5129452493e [deploy] Bundle Mercurial with hg-web
MrJuneJune <me@mrjunejune.com>
parents: 227
diff changeset
255 Nginx authentication or another trusted access layer.
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
256
227
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
257 ## Publishing
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
258
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
259 Push committed Mercurial changes to the configured server:
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
260
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
261 ```bash
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
262 hg push
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
263 ```
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
264
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
265 Then update and deploy on the server:
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
266
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
267 ```bash
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
268 ssh -t [email protected] \
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
269 'cd ~/zenbu && hg update default && bazel run //hg-web:deploy'
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
270 ```
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
271
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
272 The SSH key may prompt for its passphrase. `//hg-web:deploy` builds the release
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
273 bundle through Bazel before running the atomic promotion, health check, and
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
274 rollback workflow.
8bb0ac8f4587 [hg-web] Add Bazel deployment target
MrJuneJune <me@mrjunejune.com>
parents: 224
diff changeset
275
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
276 ## Forge capability tree
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
277
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
278 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
279 Zenbu Forge
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
280 ├── Repository
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
281 │ ├── File and directory browsing available
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
282 │ ├── Syntax highlighting available
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
283 │ ├── README rendering available
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
284 │ ├── Commit graph available
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
285 │ ├── Changeset detail and diff available
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
286 │ ├── Branches, bookmarks, and tags planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
287 │ ├── File history and blame planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
288 │ └── Search planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
289 ├── Collaboration
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
290 │ ├── Authentication and authorization planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
291 │ ├── Changeset review planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
292 │ ├── Issues planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
293 │ └── Releases and artifacts planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
294 └── Automation
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
295 ├── Mercurial incoming/changegroup hook planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
296 ├── Durable SQLite job queue planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
297 ├── Isolated Bazel runner planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
298 ├── Live logs and job status API planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
299 ├── Forge status and log screens planned
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
300 ├── Artifact retention planned
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
301 └── Atomic deploy, health check, rollback available
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
302 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
303
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
304 ## Automation data flow
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
305
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
306 The Actions-like subsystem should extend the existing server rather than
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
307 replace it:
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
308
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
309 ```text
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
310 hg push
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
311 -> Mercurial hook records repository + revision
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
312 -> small enqueue command writes a SQLite job
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
313 -> runner service claims one queued job
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
314 -> isolated shared checkout updates to the exact revision
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
315 -> Bazel build and test steps stream logs
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
316 -> job result and artifacts are recorded
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
317 -> hg-web status API exposes the result
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
318 -> custom React screens render runs, steps, logs, and artifacts
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
319 -> successful protected jobs may call atomic deployment
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
320 ```
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
321
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
322 Start with one runner on the same host. Keep the hook fast, never execute build
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
323 steps inside the Mercurial request, and make the queue durable before adding
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
324 parallel or remote runners.
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
325
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
326 ## Safe extension order
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
327
221
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
328 1. Add branches, bookmarks, tags, file history, blame, and search.
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
329 2. Add the hook, SQLite queue, single runner, and retained logs.
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
330 3. Add run/status/log pages using the existing custom UI.
ce7f4400c2de [hg-web] Harden forge and add changeset UI
MrJuneJune <me@mrjunejune.com>
parents: 218
diff changeset
331 4. Add authentication and authorization before accepting public pushes or
218
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
332 user-defined automation.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
333
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
334 ## Invariants
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
335
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
336 - Keep public application code on Seobeo APIs.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
337 - Decode and validate every path before forwarding it to Mercurial.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
338 - Keep `/repo` binary-safe; bundle data can contain null bytes.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
339 - Do not buffer large wire-protocol responses through the regular HTTP client.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
340 - Keep backend route names synchronized with frontend fetch and navigation code.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
341 - Preserve accurate status codes, content lengths, and content types.
921ca3086879 [hg-web] Add architecture wiki tree
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
342 - Keep secrets in service-owned environment files, not in source or job logs.