calendar

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