tracker

7.8 KB

1. // THE SESSION LAYER — a port of the archived hl:web's web_session.hl (mission 093,
2. // 252, 255, 261), re-read 2026-09-12. The design is the creator's own from
3. // hybrilior: one cookie holds a random id, the SERVER holds everything else; a
4. // session fans out to every socket that shares the cookie; delivery is a
5. // predicate per socket (here: the app's `audience`).
6. //
7. // THE FILE IS THE SESSION; MEMORY IS A CACHE OF THE ONES IN FLIGHT. A lookup
8. // misses in memory, reads ONE file, revives it. Nothing loads the directory at
9. // boot; a restart is a cold cache, not a wipe. The boot sweep walks the store
10. // once to REMOVE expired files, never to revive.
11. //
12. // THE FILENAME IS A HASH OF THE ID, NEVER THE ID: a value a client sent must not
13. // become a path, and `ls` on the store must not hand out live ids.
14. //
15. // THREE CLOCKS, all seconds: `maxAge` is how long a session stays VALID after its
16. // last touch (the cookie's Max-Age too); `idle` how long it stays RESIDENT in
17. // memory with no live socket (eviction is non-destructive — the file is the
18. // truth — so a short clock is safe); `sweepEvery` how often the sweep may run,
19. // piggybacking on real requests (no timer: a site with no requests has nothing
20. // to sweep). `stampDrift` bounds how far the on-disk `seen` may lag the one in
21. // memory, so an active session does not cost a disk write per asset request.
22. //
23. // `dir` is the store's absolute path, or null for memory only (the app's
24. // `sessionDir = false`). The default the framework hands in is `<project>/.sessions`
25. // — a DOT directory, which the dev watcher skips by construction (measured in the
26. // archive: a store inside the watched tree made every session write a re-analysis).
27. import HlwSession from './session.hl'
28. import { randomToken } from 'hl:http1'
29. import { now } from 'hl:time'
30. import { sha256 } from 'hl:crypto'
31. import { readFile, listDir, exists, writeFile, mkDir, remove } from 'hl:fs'
33. String dir = null
34. Number maxAge = 1209600
35. Number idle = 900
36. Number sweepEvery = 300
37. Number stampDrift = 60
38. String cookie = 'hlsid'
39. Boolean secure = false // the app is reached over https: the cookie carries `Secure`
40. String domain = '' // the cookie's `Domain` (ticket #44): '' = this host only
42. map = {} // id → Session, the resident ones
43. persistedSeen = {} // id → the `seen` last written to disk (write avoidance only)
44. lastSweep = 0
45. reported = {} // path → true: a foreign file in the store, said once
47. // ---- the store --------------------------------------------------------------------
48. path(sid) {
49. if (dir == null) { return null }
50. return dir + '/' + sha256(sid)
51. }
53. open() {
54. if (dir != null) { mkDir(dir, 448) }
55. lastSweep = now()
56. if (dir != null) {
57. let n = sweepStore(now() - maxAge * 1000)
58. if (n > 0) { console.log('sessions: boot sweep removed ' + n + ' expired session file(s) from ' + dir) }
59. }
60. return null
61. }
63. load(sid) {
64. let p = path(sid)
65. if (p == null || !exists(p)) { return null }
66. let raw = readFile(p)
67. if (raw == null || !isSessionText(raw)) { return null }
68. let rec = JSON.parse(raw)
69. if (rec == null || rec.id != sid) { return null }
70. let s = rec > new HlwSession()
71. map[sid] = s
72. persistedSeen[sid] = s.seen
73. return s
74. }
76. put(s) {
77. let p = path(s.id)
78. if (p == null) { return null }
79. if (!exists(dir)) { mkDir(dir, 448) }
80. writeFile(p, JSON.stringify(s), 384)
81. persistedSeen[s.id] = s.seen
82. return null
83. }
85. drop(sid) {
86. let p = path(sid)
87. if (p != null) { remove(p) }
88. persistedSeen[sid] = null
89. return null
90. }
92. // ---- the cookie ----------------------------------------------------------------
93. parseCookies(header) {
94. let out = {}
95. if (header == null) { return out }
96. for (part of header.split(';')) {
97. let eq = part.indexOf('=')
98. if (eq > 0) { out[part.slice(0, eq).trim()] = part.slice(eq + 1).trim() }
99. }
100. return out
101. }
103. cookieHeader(sid) {
104. return cookie + '=' + sid + '; Path=/; HttpOnly; SameSite=Lax; Max-Age=' + maxAge + (domain != '' ? '; Domain=' + domain : '') + (secure ? '; Secure' : '')
105. }
107. // ---- the map ---------------------------------------------------------------------
108. // the session a cookie header names: resident, or revived from its file; null when
109. // it names none (no cookie, or an id nobody knows — that browser is anonymous)
110. resolve(cookieHeader) {
111. return byId(parseCookies(cookieHeader)[cookie])
112. }
114. byId(sid) {
115. if (sid == null) { return null }
116. let s = map[sid]
117. if (s == null) { s = load(sid) }
118. if (s == null) { return null }
119. touch(s)
120. return s
121. }
123. // a new session, resident and on disk; the caller sets the cookie
124. mint() {
125. maybeSweep([])
126. let sid = randomToken(32)
127. let s = new HlwSession(id = sid, created = now(), seen = now())
128. map[sid] = s
129. put(s)
130. return s
131. }
133. // ONE WRITE PATH for the stamp: every request or frame that presents a session
134. // moves `seen`; the file follows only when it has drifted `stampDrift` seconds
135. touch(s) {
136. s.seen = now()
137. if (dir != null) {
138. let last = persistedSeen[s.id]
139. if (last == null || s.seen - last >= stampDrift * 1000) { put(s) }
140. }
141. return null
142. }
144. // what a face wrote (login, a cart) reaches the file now, not at the next drift
145. save(s) {
146. if (s != null) { put(s) }
147. return null
148. }
150. // ---- the sweep -------------------------------------------------------------------
151. // `live` is the set of session ids with an open socket — those are never evicted
152. maybeSweep(live) {
153. if (now() - lastSweep >= sweepEvery * 1000) { sweep(live) }
154. return null
155. }
157. sweep(live) {
158. lastSweep = now()
159. let cutoff = now() - maxAge * 1000
160. let cold = now() - idle * 1000
161. let evicted = 0
162. let expired = 0
163. let next = {}
164. for (k of map.keys()) {
165. let s = map[k]
166. if (s == null) {
167. // dropped earlier
168. } else if (s.seen <= cutoff) {
169. drop(k)
170. expired = expired + 1
171. } else if (dir != null && s.seen <= cold && !live.includes(k)) {
172. persistedSeen[k] = null
173. evicted = evicted + 1
174. } else {
175. next[k] = s
176. }
177. }
178. map = next // a fresh hybrid: the compaction (archive, mission 261)
179. let dropped = 0
180. if (dir != null) { dropped = sweepStore(cutoff) }
181. if (evicted + expired + dropped > 0) {
182. console.log('sessions: sweep — evicted ' + evicted + ', expired ' + expired + ', ' + dropped + ' file(s) removed, ' + map.keys().length + ' resident')
183. }
184. return null
185. }
187. sweepStore(cutoff) {
188. let gone = 0
189. if (!exists(dir)) { return gone }
190. for (e of listDir(dir)) {
191. let raw = isSessionName(e.name) && e.type == 'file' ? readFile(e.path) : null
192. if (raw != null && !isSessionText(raw)) { raw = null }
193. if (raw == null) { foreign(e) }
194. if (raw != null) {
195. let rec = JSON.parse(raw)
196. if (rec != null && rec.seen <= cutoff) {
197. remove(e.path)
198. persistedSeen[rec.id] = null
199. gone = gone + 1
200. }
201. }
202. }
203. return gone
204. }
206. // ---- what the store holds that is not a session -----------------------------------
207. // A FILE THAT IS NOT A SESSION IS SKIPPED, NEVER PARSED. The store is a directory an
208. // operator can put anything into (a marker, an editor's backup, a copy), and
209. // `JSON.parse` aborts the program on text that is not JSON — at the boot sweep that was
210. // the whole server, before it served anything (ticket #26). Every file this layer
211. // writes is named by a sha256 (64 lowercase hex characters) and holds a Session's JSON,
212. // whose keys come out sorted, so it opens with `{"created":`; `writeFile` renames a
213. // finished temp file over the target, so a torn session file cannot occur. A file that
214. // is not that shape is left where it is, and said once.
215. isSessionName(name) {
216. if (name.length != 64) { return false }
217. for (c of name.split('')) {
218. if (!'0123456789abcdef'.includes(c)) { return false }
219. }
220. return true
221. }
223. isSessionText(raw) {
224. let t = raw.trim()
225. return t.startsWith('{"created":') && t.endsWith('}')
226. }
228. foreign(e) {
229. if (reported[e.path] == null) {
230. reported[e.path] = true
231. console.log('sessions: skipped ' + e.path + ' — not a session file (the store names its files by a hash and writes JSON); it is left where it is')
232. }
233. return null
234. }