tickets

8.7 KB

1. // lib/api-helpers.hl — the plumbing of the function routes (lib/api.hl): query strings, bodies, answers, who is
2. // calling (token or app key), the Markdown Accept check, the small HTML page. Statics only; no topic logic here.
3. import { Response } from 'hl:http1'
4. import { jsonErrorAt } from './jsoncheck.hl'
5. import { userOfBearer } from './users.hl'
6. import { connectionOfKey, personOf } from './connections.hl'
7. import { states, stateOf } from './tickets-helpers.hl'
9. static jsonHeaders = { 'Content-Type' = 'application/json; charset=utf-8' }
11. static reply = (status, value) => {
12. return new Response(JSON.stringify(value), { status = status headers = jsonHeaders })
13. }
15. static fail = (status, message) => { return reply(status, { error = message }) }
17. // `?a=1&b=x` of a request path → { a = '1', b = 'x' } ('+' is a space; hl:http1
18. // has already percent-decoded the path)
19. static queryOf = (path) => {
20. out = {}
21. q = path.indexOf('?')
22. if (q < 0) { return out }
23. for (pair of path.slice(q + 1).split('&')) {
24. if (pair != '') {
25. let eq = pair.indexOf('=')
26. if (eq < 0) { out[pair] = '' } else { out[pair.slice(0, eq)] = pair.slice(eq + 1).replaceAll('+', ' ') }
27. }
28. }
29. return out
30. }
32. // the request body as JSON, or null when it is not
33. static bodyOf = (req) => {
34. if (req.body == null || req.body == '') { return null }
35. return JSON.parse(req.body)
36. }
38. // THE API IS STRICT (ticket #10): a malformed report must not be filed half-read. A body
39. // is a JSON object whose keys are all in `required` or `optional`, every value is a
40. // String, and every required one is non-empty after trimming. Answers null (fine) or
41. // { error, field } — the first offence, naming the field.
42. // (a list has no concat() in this build — NotCallable, hybriel #6's family)
43. static allowedOf = (required, optional) => {
44. all = []
45. for (k of required) { all.push(k) }
46. for (k of optional) { all.push(k) }
47. return all.join(', ')
48. }
50. static bodyError = (b, required, optional) => {
51. if (b == null || hlTypeName(b) != 'Hybrid' || b.length != null) {
52. return { error = 'the body must be a JSON object' field = '' }
53. }
54. for (k of b.keys()) {
55. // ticket #7: the author is the token's user — a body that still names one is refused
56. // (not silently ignored), so a client learns that its field does nothing
57. if (k == 'author') {
58. return { error = "no field 'author' any more: the author is the user of your API token" field = 'author' }
59. }
60. if (!required.includes(k) && !optional.includes(k)) {
61. return { error = "unknown field '" + k + "' (allowed: " + allowedOf(required, optional) + ')' field = k }
62. }
63. if (hlTypeName(b[k]) != 'String') {
64. return { error = "field '" + k + "' must be a string, not " + hlTypeName(b[k]) field = k }
65. }
66. }
67. for (k of required) {
68. if (b[k] == null) { return { error = "field '" + k + "' is required" field = k } }
69. if (b[k].trim() == '') { return { error = "field '" + k + "' must not be empty" field = k } }
70. }
71. return null
72. }
74. static refuse = (e) => { return reply(400, e) }
76. // ticket #7: an API write without a valid token (missing, malformed, unknown, revoked) → 401
77. static unauthorized = () => {
78. return new Response(JSON.stringify({ error = 'an API write needs Authorization: Bearer <token> — log in with ident and create a token on /you' }), { status = 401 headers = { 'Content-Type' = 'application/json; charset=utf-8' 'WWW-Authenticate' = 'Bearer' } })
79. }
81. // a POST body, checked: { body } or { bad } (bad = the 400 answer's value).
82. // Invalid JSON is refused by jsoncheck.hl BEFORE JSON.parse ever sees it (ticket #15,
83. // workaround for hybriel #12: an uncaught JSON.parse would answer 500 with source paths).
84. static readBody = (req, required, optional) => {
85. if (req.body != null && req.body != '') {
86. at = jsonErrorAt(req.body)
87. if (at >= 0) { return { bad = { error = 'invalid JSON at character ' + at } } }
88. }
89. b = bodyOf(req)
90. return { body = b bad = bodyError(b, required, optional) }
91. }
93. // a refusal of a topic function: 403 when the role is missing, else 400
94. static denied = (r) => {
95. if (r.forbidden == true) { return reply(403, { error = r.error field = r.field }) }
96. return refuse({ error = r.error field = r.field })
97. }
99. // ---- who is calling --------------------------------------------------------------------------------
100. // WRITES NEED A TOKEN (ticket #7): `Authorization: Bearer <token>` (users.hl; a logged-in user
101. // makes tokens on /you). No / bad / revoked token → 401, checked BEFORE the body.
102. // the token's user of an API write, or null (→ 401)
103. static apiUser = (req) => { return userOfBearer(req.headers['authorization']) }
105. // WHO WRITES, for the endpoints an app's KEY may also use (ticket #21: create a ticket, comment, change the state):
106. // { user } for a user's token, { conn } for a project key (connections.hl), null = 401 (checked before the body)
107. static apiAuth = (req) => {
108. h = req.headers['authorization']
109. u = userOfBearer(h)
110. if (u != null) { return { user = u } }
111. c = connectionOfKey(h)
112. return c != null ? { conn = c } : null
113. }
115. // the acting user inside project `projectId`: { user } or { response }. A key reaches ITS project only and names the
116. // person by `X-Tickets-Identity`; the project's roles then decide as for any user.
117. static actorIn = (auth, req, projectId) => {
118. if (auth.user != null) { return { user = auth.user } }
119. if (projectId == null || auth.conn.project != projectId) { return { response = reply(403, { error = 'this key belongs to another project' field = '' }) } }
120. a = personOf(req.headers['x-tickets-identity'])
121. if (a.error != null) { return { response = reply(403, { error = a.error field = '' }) } }
122. return { user = a.user }
123. }
125. // ---- list filters ----------------------------------------------------------------------------------
126. static stateFilter = (q) => {
127. if (q.state == null || q.state == '') { return { state = null } }
128. st = stateOf(q.state)
129. if (st == null) { return { bad = fail(400, 'unknown state — one of: ' + states.join(', ')) } }
130. return { state = st }
131. }
133. // the filters of a list, for the Markdown heading ('' = none)
134. static filterLabel = (project, state) => {
135. parts = []
136. if (project != null) { parts.push('project ' + project) }
137. if (state != null) { parts.push('state ' + state) }
138. return parts.join(', ')
139. }
141. // ---- THE MARKDOWN READ VIEW's request side (ticket #6; the documents: lib/mdview.hl) -----------------
142. // does the request ask for Markdown? `Accept` names text/markdown with q > 0 and prefers it to
143. // application/json (a higher q, or the same q and listed first). No Accept / */* → JSON.
144. static qOf = (part) => {
145. let q = 1
146. for (p of part.split(';')) {
147. let kv = p.trim()
148. if (kv.startsWith('q=')) { q = toNumber(kv.slice(2)) }
149. }
150. return q == null ? 0 : q
151. }
152. static wantsMarkdown = (req) => {
153. h = req.headers['accept']
154. if (h == null || hlTypeName(h) != 'String') { return false }
155. let md = -1
156. let js = -1
157. let mdAt = -1
158. let jsAt = -1
159. let i = 0
160. for (part of h.toLowerCase().split(',')) {
161. let type = part.split(';')[0].trim()
162. if (type == 'text/markdown' && mdAt < 0) {
163. md = qOf(part)
164. mdAt = i
165. }
166. if (type == 'application/json' && jsAt < 0) {
167. js = qOf(part)
168. jsAt = i
169. }
170. i = i + 1
171. }
172. if (md <= 0) { return false }
173. if (js < 0) { return true }
174. return md > js || (md == js && mdAt < jsAt)
175. }
177. static markdownReply = (text) => {
178. return new Response(text, { status = 200 headers = { 'Content-Type' = 'text/markdown; charset=utf-8' 'Vary' = 'Accept' } })
179. }
181. // ---- answers that are not JSON ---------------------------------------------------------------------
182. // a small HTML page (the login callback, /connect): a title and one message
183. static htmlPage = (status, title, text) => {
184. body = '<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>tickets | ' + title + '</title><style>body{margin:0;padding:1.5rem 1rem;font:16px/1.5 system-ui,sans-serif;color:rgb(195, 200, 205);background:rgb(25, 30, 35)}main{max-width:34rem;margin:0 auto;display:grid;gap:1rem}h1{margin:0;font-size:1.3rem;color:rgb(245, 250, 255)}p{margin:0}a{color:#c586c0}.error{color:#f44747}</style></head><body><main><h1>' + title + '</h1><p id="error" class="error">' + text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;') + '</p><p><a id="home" href="/">back to the tickets</a></p></main></body></html>'
185. return new Response(body, { status = status headers = { 'Content-Type' = 'text/html; charset=utf-8' 'Cache-Control' = 'no-store' } })
186. }
188. // a page that moved for good (301) / a page that names nothing (404), as plain text
189. static moved = (to) => {
190. return new Response('moved to ' + to, { status = 301 headers = { 'Location' = to 'Content-Type' = 'text/plain; charset=utf-8' } })
191. }
192. static missing = (message) => { return new Response(message, { status = 404 headers = { 'Content-Type' = 'text/plain; charset=utf-8' } }) }