tickets

3.6 KB

1. // api.hl — the JSON API's plumbing: query strings, bodies, answers. Statics only;
2. // the routes themselves are in project.hl (a function route is `(route, req) => …`).
3. import { Response } from 'hl:http1'
4. import { jsonErrorAt } from './jsoncheck.hl'
6. static jsonHeaders = { 'Content-Type' = 'application/json; charset=utf-8' }
8. static reply = (status, value) => {
9. return new Response(JSON.stringify(value), { status = status headers = jsonHeaders })
10. }
12. static fail = (status, message) => { return reply(status, { error = message }) }
14. // `?a=1&b=x` of a request path → { a = '1', b = 'x' } ('+' is a space; hl:http1
15. // has already percent-decoded the path)
16. static queryOf = (path) => {
17. let out = {}
18. let q = path.indexOf('?')
19. if (q < 0) { return out }
20. for (pair of path.slice(q + 1).split('&')) {
21. if (pair != '') {
22. let eq = pair.indexOf('=')
23. if (eq < 0) { out[pair] = '' } else { out[pair.slice(0, eq)] = pair.slice(eq + 1).replaceAll('+', ' ') }
24. }
25. }
26. return out
27. }
29. // the request body as JSON, or null when it is not
30. static bodyOf = (req) => {
31. if (req.body == null || req.body == '') { return null }
32. return JSON.parse(req.body)
33. }
35. // THE API IS STRICT (ticket #10): a malformed report must not be filed half-read. A body
36. // is a JSON object whose keys are all in `required` or `optional`, every value is a
37. // String, and every required one is non-empty after trimming. Answers null (fine) or
38. // { error, field } — the first offence, naming the field.
39. // (a list has no concat() in this build — NotCallable, hybriel #6's family)
40. static allowedOf = (required, optional) => {
41. let all = []
42. for (k of required) { all.push(k) }
43. for (k of optional) { all.push(k) }
44. return all.join(', ')
45. }
47. static bodyError = (b, required, optional) => {
48. if (b == null || hlTypeName(b) != 'Hybrid' || b.length != null) {
49. return { error = 'the body must be a JSON object' field = '' }
50. }
51. for (k of b.keys()) {
52. // ticket #7: the author is the token's user — a body that still names one is refused
53. // (not silently ignored), so a client learns that its field does nothing
54. if (k == 'author') {
55. return { error = "no field 'author' any more: the author is the user of your API token" field = 'author' }
56. }
57. if (!required.includes(k) && !optional.includes(k)) {
58. return { error = "unknown field '" + k + "' (allowed: " + allowedOf(required, optional) + ')' field = k }
59. }
60. if (hlTypeName(b[k]) != 'String') {
61. return { error = "field '" + k + "' must be a string, not " + hlTypeName(b[k]) field = k }
62. }
63. }
64. for (k of required) {
65. if (b[k] == null) { return { error = "field '" + k + "' is required" field = k } }
66. if (b[k].trim() == '') { return { error = "field '" + k + "' must not be empty" field = k } }
67. }
68. return null
69. }
71. static refuse = (e) => { return reply(400, e) }
73. // ticket #7: an API write without a valid token (missing, malformed, unknown, revoked) → 401
74. static unauthorized = () => {
75. 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' } })
76. }
78. // a POST body, checked: { body } or { bad } (bad = the 400 answer's value).
79. // Invalid JSON is refused by jsoncheck.hl BEFORE JSON.parse ever sees it (ticket #15,
80. // workaround for hybriel #12: an uncaught JSON.parse would answer 500 with source paths).
81. static readBody = (req, required, optional) => {
82. if (req.body != null && req.body != '') {
83. let at = jsonErrorAt(req.body)
84. if (at >= 0) { return { bad = { error = 'invalid JSON at character ' + at } } }
85. }
86. let b = bodyOf(req)
87. return { body = b bad = bodyError(b, required, optional) }
88. }