notes

15.9 KB

1. # hl:web — the web framework
3. `hl:web` serves an app's pages from the server and keeps them live in the browser. It is written
4. in Hybriel: `WebFramework.hl` is the server half, `client.hl` the browser half, and `compile.hl`
5. turns each component's View into that component's own code. The model behind it (components,
6. Views, realms, the boundary) is in [COMPONENTS.md](../../COMPONENTS.md). This page lists the rules
7. an app is held to. Each rule is a located refusal at boot unless it says otherwise.
9. ## Starting an app
11. ```hybriel
12. import WebFramework from 'hl:web'
13. import Home from './components/home.hl'
14. import Styles from './styles.hl'
16. routes = [ { pattern = "/" component = Home } ]
17. server = new WebFramework(routes = routes, styles = Styles, port = 8080)
18. ```
20. Settings may be passed as named arguments. Most of them may instead be members of the file that
21. runs the `new`:
23. | setting | default | meaning |
24. |---|---|---|
25. | `routes` | `[]` | the route table (below); pass it as an argument |
26. | `styles` | none | the app's styles file: the imported class, or a path string. It must be in the project graph |
27. | `port` | 8080 | the port to listen on |
28. | `host` | `HL_HOST`/`HOST`, else 0.0.0.0 | the interface to bind |
29. | `audience` | `{}` | per outward event, who receives it (see Events) |
30. | `minify` | false | one-line HTML and compact modules |
31. | `watchMode` | true | a saved `.hl` file re-analyses the app and reloads every open tab |
32. | `sessionDir` | `<app>/.sessions` | where sessions are stored; `false` keeps them in memory |
33. | `sessionMaxAge`, `sessionIdle`, `sweepInterval` | 14 days, 15 min, 5 min | the session clocks, in seconds |
34. | `sessionCookie` | `hlsid` | the cookie's name: letters, digits, `-` and `_` |
35. | `sessionSecure` | false | set the cookie's `Secure` flag (for an app behind https) |
36. | `appTitle`, `appDescription`, `appImage`, `appFavicon`, `meta` | none | the head every page gets unless it declares its own |
37. | `links` | none | a list of hybrids, one `<link>` each in every page's head (`{ rel = 'preconnect' href = '…' }`) |
38. | `appIcons`, `appShortName`, `appThemeColor`, `appBackgroundColor`, `appTouchIcon`, `appManifest` | none | make the app installable: a web app manifest, linked from every head (see Offline and installable) |
39. | `offline` | none | the pages kept offline: a service worker, their state in IndexedDB, a queue for their emits |
40. | `pingEvery`, `pongWithin` | 25, 10 | the dead-socket clock, in seconds: the browser pings every `pingEvery`, and a pong missing after `pongWithin` closes the socket and reconnects |
41. | `uploadMax` | 1 GiB | the largest file an emit may carry, in bytes (see Files in an emit) |
43. An app runs on one web framework. If its files reach two packages that hold a `WebFramework.hl`
44. (for example an old vendored copy beside this one), it is refused at boot, naming the import row
45. of each.
47. ## Routes
49. Each entry has a `pattern` (`/posts/:id`, `/assets/*`) and one kind:
51. | kind | answers with |
52. |---|---|
53. | `component = Home` or `"./components/home.hl"` | the page, rendered on the server; the component must be imported by the app, and must declare a View |
54. | `function = (route, req) => { … }` | what the function returns (a Hybrid becomes JSON); `req.session` is the cookie's session, or null |
55. | `direct = "text"` | that text |
56. | `file = "./x"` | one file |
57. | `directory = "./assets"` | the files under a directory |
59. A named group (`:id`) reaches the component as a construction argument of the same name: declare
60. `id = null` at its root. A named wildcard does the same with the rest of the path:
61. `/code/*path` gives `path = 'src/lib/util.hl'` for `/code/src/lib/util.hl`, on the first load and
62. on a navigation. A bare `*` has no name a member could take; it is what a `directory` route
63. serves from.
65. The request itself reaches a component the same way, and only one that declares the member
66. (COMPONENTS.md): `session = null` gets the session, `host = null` the host without its port,
67. `headers = null` the request's headers as a hash with lowercase names —
68. `headers['accept-language']`. On a client navigation they are the headers of the request the
69. navigation crossed on, so they are still the browser's own: the socket's upgrade request, or the
70. `POST /__hl/emit` under the fallback. `cookie`, `authorization` and `proxy-authorization` are left
71. out, because a member is state and state reaches page script.
73. ## Components
75. A component is a `.hl` file with a `View`. Its root members are its state, and are constructed on
76. the server for each request.
78. **A View attribute is a literal, a member or a field path.** `href = "/"`, `href = url` and
79. `href = p.url` are allowed. `href = '/posts/' + id` is refused at its line: declare
80. `postUrl = '/posts/' + id` at the file's root and write `href = postUrl`. The same holds for a
81. value bound on a component reference (`Card { title = t }`) and for the condition of an `if` in a
82. View, which may also be a `for` row variable.
84. **An attribute name that is not an identifier is quoted.** `"aria-hidden" = "true"` and
85. `"data-page" = it.target` render as written and bind like any attribute, in a `for` row too. A
86. camelCase name is not rewritten (`ariaHidden` renders as `ariaHidden`). `data-page = it.target`
87. unquoted is refused at its line, naming the quoted form.
89. **A bound attribute in a `for` row follows the row** on every update of the list: a new list, a
90. `push`, an `upsert` and a write into a row's record (`items[0].title = …`) repaint it, as they
91. repaint the row's text and class.
93. **The tree carries the elements the HTML parser implies.** `table { tr { td { … } } }` is rendered
94. as `table > tbody > tr > td`, because that is the tree the browser builds from the HTML, and the
95. page is continued from the tree the browser built. The pairs are listed in `view.hl`
96. (`impliedElements`): `tr`, `td` and `th` under `table` get a `tbody`, `td` and `th` under `tbody`,
97. `thead` or `tfoot` get a `tr`, and `col` gets a `colgroup`. Consecutive children that need the same
98. container share one.
100. The other rules:
101. - A View reads only names the file declares. A name it declares nowhere is refused.
102. - `parent './main.hl'` wraps a page in a shell. The shell declares `slot = null` and places
103. `slot` in its View exactly once. A component that is filled (`Card { p { … } }`) must declare a
104. slot too.
105. - `body { … }` is allowed only as the root of a View, and a page wrapped by a parent cannot have
106. one: the shell owns the body.
107. - A View cannot render itself, directly or through other components.
108. - A Style rule cannot be written on a component reference. Write it on an element inside that
109. component.
110. - A page's head comes from its members `__title`, `__description`, `__image`, `__favicon` and
111. `__meta`, and falls back to the app's `appTitle`, `appDescription`, `appImage`, `appFavicon` and
112. `meta`. A handler that writes one of them updates the document.
114. ## Events
116. `on name(…)` handlers and `emit` statements cross between the browser and the server over a
117. WebSocket on the app's own port. `POST /__hl/emit` is the fallback for a peer without a socket.
118. A handler that takes `session` as its last parameter gets the connection's session from the
119. server, never from the peer.
121. An outward event reaches the tab that caused it. To send it to other connections, give it an
122. `audience` entry: a function of the event's arguments and the receiving connection's session that
123. answers true or false.
125. A value-form emit (`answer = emit server ask()`) waits for one answer, so it has one answerer.
126. If two files in the target realm answer the event, it is refused.
128. **A write anywhere repaints what it wrote** (tickets #98, #99), from the compiler's write
129. sets, never by watching the members:
130. - A listener repaints what its handler writes when the handler is done. A handler still
131. waiting after the task that started it (a network answer, `new Promise(…)`) has its
132. write set painted then too, so what it wrote before the wait shows while it waits.
133. - A function made inside a component — an `XMLHttpRequest`'s `onload` or `onprogress`, a
134. timer, a Promise's executor, a `then` — is compiled so that every return of it is
135. announced with the site it was made at. What it writes (a member, a push into one, a
136. field inside one, and what the methods it calls and the events it emits write) is
137. repainted after the task that ran it. A function that writes no member repaints nothing.
138. - A repaint the listener already made in the same task is not made twice.
140. **After a face that takes `session`** (tickets #121, #122), the server re-derives the
141. members that read `session` for the tabs that mounted the component, with the page's own
142. route params, and ships them in the ack (`sync`); the browser takes them as writes.
143. - A member that reads `session` and calls an imported class, directly or through a local
144. method or static, is computed on the server only and never re-derived in the browser.
145. - Such a member is already up to date when the handler continues, so a client handler that
146. appends the face's returned row to a list derived from `session` shows it twice. Assign
147. from what the sync brought, or leave the list to the sync.
148. - A member derived from `session` that needs a server-only resource (a database) must reach
149. it through an imported class or a static of one; a plain copy (`me = session.user.id`) is
150. derived everywhere.
152. ### Files in an emit
154. A browser `File` (an input's `ev.target.files[0]`, a dropped file) or a list of them
155. (`ev.target.files`) may be an argument of an `emit server …`. It never rides the socket:
156. before the emit goes out, the client half sends each file to `/__hl/upload` as its own HTTP
157. requests, with the page's session cookie, in parts of 1 MiB. The face gets the file in its
158. place as `{ bytes, name, type, size }` (`bytes` a `Bytes`), or a list of those for a list:
160. ```hybriel
161. input { type = 'file' on change(ev) { emit send(ev) } }
163. on send(ev) { saved = emit server saveFile(ev.target.files[0]) }
165. on server saveFile(file) {
166. writeFile('uploads/' + file.name, file.bytes)
167. return file.size
168. }
169. ```
171. - **Progress.** While a file is sent, every mounted component that declares
172. `on client uploadProgress(p)` gets `p = { event, index, name, sent, size }`: the emit's
173. event, the file's position among the emit's files, its name, the bytes sent so far and
174. its size.
175. - **A dropped connection.** A part that did not come back is asked for again: the client
176. waits (250 ms, doubling up to 4 s), asks the server how much of the file it has, and goes
177. on from there. After 8 drops in a row it gives up.
178. - **A failed upload ends the emit.** A file the server refuses (bigger than `uploadMax`, an
179. upload of another session) or a connection that stays down ends the emit with that error
180. instead of sending it — except a queueable emit in an offline app, which is queued with its
181. files when the connection is what failed (COMPONENTS §10): it gets the failed ack a failing face sends
182. (`{ t: 'ack', i, ok: false, error }`), so a value-form emit answers null and the error is
183. logged. The face does not run.
184. - An upload belongs to the session that started it, and one emit takes it. An upload that
185. nothing takes within an hour is dropped. The parts are held in the server's memory until
186. the emit takes them.
188. ## Offline and installable
190. The full model is [COMPONENTS.md §10](../../COMPONENTS.md). An app writes no JavaScript for any
191. of it.
193. ```hybriel
194. appTitle = "Hybriel Notes"
195. appIcons = [ { src = "/static/icon-192.png" sizes = "192x192" } { src = "/static/icon-512.png" sizes = "512x512" } ]
196. offline = [ NoteList, NoteEditor ]
197. ```
199. - `appIcons` (or `appManifest`, or `offline`) serves `/__hl/manifest.webmanifest` and links it,
200. with an apple-touch-icon, from every page's head. `appManifest`'s entries are written over the
201. generated manifest.
202. - `offline` lists pages: route components, as classes or path strings. Anything else is refused
203. at its line. The framework generates the service worker and registers it. The shell and the
204. listed pages' documents are cached, and a navigation is network-first. What the server last
205. said about a listed page is kept in IndexedDB and shown over an older cached document. A
206. statement-form `emit server …` from a listed page that does not reach the server is queued and
207. replayed in order when the socket reopens. Each queued emit carries a stable id, and the
208. server runs it once: a replay whose ack was lost is answered again without running the handler
209. (the last 200 ids per session are kept). A socket that goes silent without closing is noticed
210. by the ping and reopened. A queued emit keeps its files: IndexedDB holds them with the entry,
211. and they go up on the replay under the emit's id, once (COMPONENTS §10). A page that
212. declares `__hlQueued = 0` /
213. `__hlQueue = []` shows the queue. A page that declares `__hlOnline = true` has it follow the browser's
214. connection (`navigator.onLine`, and the online/offline events), so a View can say "you are offline".
215. - `offlineFallback = Start` (a route component, class or path string, answered by a route with no
216. parameter; needs `offline`) names a DATA-FREE page: the worker keeps its document once, fetched without
217. credentials, and shows it for any page it has nothing for while the network is down, instead of "Unavailable
218. offline". Not set: nothing changes. A page (kept or the fallback) that declares `__hlDataFree = true` is kept
219. the same way — its document is the anonymous one, and the browser keeps neither its state nor a queue for it.
220. - Kept state is per component for a member no route parameter feeds (the same list at every url of
221. the page), per url for the rest. A param page that was never loaded as a document is answered offline
222. with a kept document of the same component, booted with the url's parameters.
223. - What is kept belongs to the last user who was logged in. An expired or fresh anonymous session
224. changes nothing: that user's queue is held, and replays when the same user logs in again (the server
225. refuses a replay made for another user). Another user logging in forgets the copy (state, queue and the
226. worker's documents); an entry from before users were kept is dropped unsent. A
227. face that logs the session out forgets the copy by itself (the ack says whose session it is now);
228. an app with its own logout calls `forgetOffline()` from `hl:web`.
229. - In any app, an emit in flight when its socket closes is sent again with its id over the POST
230. fallback or the next socket, and answered there (ticket #107). A page being left
231. (`beforeunload`, `pagehide`) reopens nothing and posts nothing.
232. - `import { notify, notifyAt, notifyIn } from 'hl:web'` shows a notification now, or at a time while the page
233. is open. A closed app cannot be woken at a set time without a server push.
235. ## What it serves
237. | url | what |
238. |---|---|
239. | `/<file key>` (e.g. `/components/home.hl`) | a component's browser module |
240. | `/__hl/hl-runtime.js` | the runtime every module imports |
241. | `/__hl/web/client.js` | this package's browser half (other packages' halves are at `/__hl/<name>/client.js`) |
242. | `/__hl/app.css` | the one stylesheet, built from the styles file and every component's `Style` |
243. | `/__hl/emit` | the POST fallback for emits |
244. | `/__hl/manifest.webmanifest` | the web app manifest, for an installable app |
245. | `/__hl/sw.js`, `/__hl/web/worker.js` | the service worker's entry script and its compiled module, for an app with `offline` |
246. | `/__hl/upload` | a file of an emit, in parts (`POST` `{ name, type, size, q, n }` → `{ id, have }`, or `{ handled }` when the session handled emit `q` already; `POST ?id=&at=` one part → `{ have }`; `GET ?id=` → `{ have }`) |
248. The page loads the modules and the stylesheet as `<url>?v=<hash>`, where the hash covers everything the build serves. A url with the current hash is sent with `Cache-Control: public, max-age=31536000, immutable`, and any other url with `no-cache`. A deploy therefore changes every url, and a tab that navigates into a newer build loads that page as a full document.
250. An app's own `file` and `directory` routes keep the same url across deploys, so they answer with an `ETag` of the content and `Cache-Control: no-cache` (a route's own `Cache-Control` header replaces that). A request whose `If-None-Match` names the current tag gets a `304` with no body.