notes

12.1 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. ### Files in an emit
130. A browser `File` (an input's `ev.target.files[0]`, a dropped file) or a list of them
131. (`ev.target.files`) may be an argument of an `emit server …`. It never rides the socket:
132. before the emit goes out, the client half sends each file to `/__hl/upload` as its own HTTP
133. requests, with the page's session cookie, in parts of 1 MiB. The face gets the file in its
134. place as `{ bytes, name, type, size }` (`bytes` a `Bytes`), or a list of those for a list:
136. ```hybriel
137. input { type = 'file' on change(ev) { emit send(ev) } }
139. on send(ev) { saved = emit server saveFile(ev.target.files[0]) }
141. on server saveFile(file) {
142. writeFile('uploads/' + file.name, file.bytes)
143. return file.size
144. }
145. ```
147. - **Progress.** While a file is sent, every mounted component that declares
148. `on client uploadProgress(p)` gets `p = { event, index, name, sent, size }`: the emit's
149. event, the file's position among the emit's files, its name, the bytes sent so far and
150. its size.
151. - **A dropped connection.** A part that did not come back is asked for again: the client
152. waits (250 ms, doubling up to 4 s), asks the server how much of the file it has, and goes
153. on from there. After 8 drops in a row it gives up.
154. - **A failed upload ends the emit.** A file the server refuses (bigger than `uploadMax`, an
155. upload of another session) or a connection that stays down ends the emit with that error
156. instead of sending it: a value-form emit answers null and the located message is logged,
157. the same way as any emit the far side refuses. The face does not run.
158. - An upload belongs to the session that started it, and one emit takes it. An upload that
159. nothing takes within an hour is dropped. The parts are held in the server's memory until
160. the emit takes them.
162. ## Offline and installable
164. The full model is [COMPONENTS.md §10](../../COMPONENTS.md). An app writes no JavaScript for any
165. of it.
167. ```hybriel
168. appTitle = "Hybriel Notes"
169. appIcons = [ { src = "/static/icon-192.png" sizes = "192x192" } { src = "/static/icon-512.png" sizes = "512x512" } ]
170. offline = [ NoteList, NoteEditor ]
171. ```
173. - `appIcons` (or `appManifest`, or `offline`) serves `/__hl/manifest.webmanifest` and links it,
174. with an apple-touch-icon, from every page's head. `appManifest`'s entries are written over the
175. generated manifest.
176. - `offline` lists pages: route components, as classes or path strings. Anything else is refused
177. at its line. The framework generates the service worker and registers it. The shell and the
178. listed pages' documents are cached, and a navigation is network-first. What the server last
179. said about a listed page is kept in IndexedDB and shown over an older cached document. A
180. statement-form `emit server …` from a listed page that does not reach the server is queued and
181. replayed in order when the socket reopens. Each queued emit carries a stable id, and the
182. server runs it once: a replay whose ack was lost is answered again without running the handler
183. (the last 200 ids per session are kept). A socket that goes silent without closing is noticed
184. by the ping and reopened. A page that declares `__hlQueued = 0` /
185. `__hlQueue = []` shows the queue.
186. - `import { notify, notifyAt, notifyIn } from 'hl:web'` shows a notification now, or at a time while the page
187. is open. A closed app cannot be woken at a set time without a server push.
189. ## What it serves
191. | url | what |
192. |---|---|
193. | `/<file key>` (e.g. `/components/home.hl`) | a component's browser module |
194. | `/__hl/hl-runtime.js` | the runtime every module imports |
195. | `/__hl/web/client.js` | this package's browser half (other packages' halves are at `/__hl/<name>/client.js`) |
196. | `/__hl/app.css` | the one stylesheet, built from the styles file and every component's `Style` |
197. | `/__hl/emit` | the POST fallback for emits |
198. | `/__hl/manifest.webmanifest` | the web app manifest, for an installable app |
199. | `/__hl/sw.js`, `/__hl/web/worker.js` | the service worker's entry script and its compiled module, for an app with `offline` |
200. | `/__hl/upload` | a file of an emit, in parts (`POST` `{ name, type, size }` → `{ id }`; `POST ?id=&at=` one part → `{ have }`; `GET ?id=` → `{ have }`) |
202. 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.
204. 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.