hazards.test.ts

packages/plinth-client/test/hazards.test.ts

1. /**
2. * Tests for the three silent-failure modes documented in docs/ARCHITECTURE.md.
3. * Sample values follow the shapes seen in live responses.
4. */
6. import { describe, expect, it } from 'vitest'
7. import {
8. assertKnownParams,
9. assertReadMethod,
10. FORBIDDEN_METHODS,
11. GET_ORDERS_PARAMS,
12. PlinthForbiddenMethodError,
13. READ_METHODS,
14. isEmptyOrInvalid,
15. num,
16. PlinthUnknownParamError,
17. phpCollection,
18. readError,
19. str,
20. toPlinthDate,
21. } from '../src/hazards.js'
22. import { DROPPED_FIELDS, projectOrder, projectProduct } from '../src/projection.js'
23. import { PLINTH_RATE_LIMIT } from '../src/index.js'
25. describe('read-only enforcement', () => {
26. it('refuses the write methods by name', () => {
27. // Plinth dispatches by query param, so HTTP verb enforces nothing. A GET with
28. // method=orders.setStatus writes to production and can email customers.
29. expect(() => assertReadMethod('orders.setStatus')).toThrow(PlinthForbiddenMethodError)
30. expect(() => assertReadMethod('inventory.adjust')).toThrow(PlinthForbiddenMethodError)
31. })
33. it('says why, including the customer-email risk', () => {
34. expect(() => assertReadMethod('orders.setStatus')).toThrow(/email customers/)
35. })
37. it('refuses unknown methods too, not just the known-bad ones', () => {
38. expect(() => assertReadMethod('setSomethingNew')).toThrow(PlinthForbiddenMethodError)
39. expect(() => assertReadMethod('')).toThrow(PlinthForbiddenMethodError)
40. })
42. it('allows every read method', () => {
43. for (const m of READ_METHODS) expect(() => assertReadMethod(m)).not.toThrow()
44. })
46. it('has no write method on the allowlist', () => {
47. for (const w of FORBIDDEN_METHODS) {
48. expect(READ_METHODS as readonly string[]).not.toContain(w)
49. }
50. })
52. it('is not configurable: no env var can widen it', () => {
53. // Guards against someone adding an PLINTH_ALLOW_WRITES escape hatch later.
54. const source = assertReadMethod.toString() + READ_METHODS.join(',')
55. expect(source).not.toMatch(/process\.env|ALLOW_WRITE/i)
56. })
57. })
59. describe('fail-open parameters', () => {
60. it('refuses a param Plinth would silently drop', () => {
61. // The documented trap: phone on customers.fetch returns the FULL
62. // unfiltered list rather than erroring.
63. expect(() => assertKnownParams('orders.fetch', { phone: '555' }, GET_ORDERS_PARAMS)).toThrow(
64. PlinthUnknownParamError,
65. )
66. })
68. it('explains why, since the failure is invisible otherwise', () => {
69. expect(() => assertKnownParams('orders.fetch', { order_number: 'MD2639777' }, GET_ORDERS_PARAMS)).toThrow(
70. /UNFILTERED/,
71. )
72. })
74. it('allows every documented param', () => {
75. expect(() =>
76. assertKnownParams(
77. 'orders.fetch',
78. { order_ref: 38794, status_code: '121', since: '20260801', limit: '50' },
79. GET_ORDERS_PARAMS,
80. ),
81. ).not.toThrow()
82. })
84. it('ignores undefined values rather than rejecting them', () => {
85. expect(() => assertKnownParams('orders.fetch', { customer_ref: undefined }, GET_ORDERS_PARAMS)).not.toThrow()
86. })
87. })
89. describe('PHP collection type switching', () => {
90. it('reads a populated collection keyed 1..N', () => {
91. expect(phpCollection({ '1': { id: 'a' }, '2': { id: 'b' } })).toEqual([{ id: 'a' }, { id: 'b' }])
92. })
94. it('reads an empty collection sent as an array', () => {
95. expect(phpCollection([])).toEqual([])
96. })
98. it('handles both forms in one response, which Plinth does', () => {
99. const order = { lines: { '1': { p: 1 }, '2': { p: 2 } }, shipments: [] }
100. expect(phpCollection(order.lines)).toHaveLength(2)
101. expect(phpCollection(order.shipments)).toHaveLength(0)
102. })
104. it('survives null and undefined', () => {
105. expect(phpCollection(null)).toEqual([])
106. expect(phpCollection(undefined)).toEqual([])
107. })
108. })
110. describe('unstable numeric typing', () => {
111. it('coerces the string and number forms of the same field', () => {
112. // Real values: tax_total "0.000000" and "0.00"; ship_weight 2.72 vs
113. // unit_weight "2.724480".
114. expect(num('0.000000')).toBe(0)
115. expect(num('2.724480')).toBeCloseTo(2.72448)
116. expect(num(2.72)).toBe(2.72)
117. })
119. it('prevents the string-concatenation bug', () => {
120. const a = '1450'
121. const b = 162.3375
122. // @ts-expect-error demonstrating the bug this exists to prevent
123. expect(a + b).toBe('1450162.3375')
124. expect(num(a) + num(b)).toBeCloseTo(1612.3375)
125. })
127. it('falls back rather than producing NaN', () => {
128. expect(num('')).toBe(0)
129. expect(num(null)).toBe(0)
130. expect(num('not a number', -1)).toBe(-1)
131. })
133. it('treats null and empty string alike, as Plinth does', () => {
134. expect(str(null)).toBeNull()
135. expect(str('')).toBeNull()
136. expect(str(' ')).toBeNull()
137. expect(str('Northline Print (orders@northlineprint.example)')).toBe('Northline Print (orders@northlineprint.example)')
138. })
139. })
141. describe('date format', () => {
142. it('converts ISO to yyyymmdd', () => {
143. expect(toPlinthDate('2026-08-09')).toBe('20260809')
144. })
146. it('puts the month before the day', () => {
147. // yyyyddmm would silently return a different window for any day <= 12.
148. expect(toPlinthDate('2026-08-09')).not.toBe('20260908')
149. })
151. it('rejects anything that is not ISO rather than sending garbage', () => {
152. expect(() => toPlinthDate('09/08/2026')).toThrow()
153. })
154. })
156. describe('ambiguous errors', () => {
157. it('recognizes that "Invalid request" also means no results', () => {
158. expect(isEmptyOrInvalid({ error: 'Invalid request' })).toBe(true)
159. })
161. it('reads both error shapes', () => {
162. expect(readError({ error: 'Bad since date' })).toBe('Bad since date')
163. expect(readError({ notice: 'No match' })).toBe('No match')
164. })
166. it('does not treat a real result as an error', () => {
167. expect(readError({ order_map: {} })).toBeNull()
168. expect(isEmptyOrInvalid({ order_map: {} })).toBe(false)
169. })
171. it('does not classify rate limiting as empty', () => {
172. // This one IS transient and should be retried; "Invalid request" must not be.
173. expect(isEmptyOrInvalid({ error: 'Too many requests. Slow down and retry.' })).toBe(false)
174. })
175. })
177. describe('projection: internal tool, per the data-handling rule, not the Northgate rules', () => {
178. const order = {
179. order_ref: 38794,
180. status_label: 'On Press',
181. grand_total: 1843.275,
182. first_name: 'Jordan',
183. last_name: 'Hale',
184. company_name: 'Harbor Signs',
185. email: 'Jordan.Hale@harborsigns.example',
186. phone: '5550100123',
187. bill_street: '100 Example Way',
188. ship_postcode: '00000',
189. }
191. it('keeps names and companies, which make a row readable', () => {
192. const p = projectOrder(order)
193. expect(p.first_name).toBe('Jordan')
194. expect(p.company_name).toBe('Harbor Signs')
195. })
197. it('drops contact details and addresses no panel renders', () => {
198. const p = projectOrder(order)
199. expect(p).not.toHaveProperty('email')
200. expect(p).not.toHaveProperty('phone')
201. expect(p).not.toHaveProperty('bill_street')
202. expect(p).not.toHaveProperty('ship_postcode')
203. })
205. it('keeps the operational fields', () => {
206. const p = projectOrder(order)
207. expect(p.order_ref).toBe(38794)
208. expect(p.status_label).toBe('On Press')
209. expect(p.grand_total).toBeCloseTo(1843.275)
210. })
212. it('drops the artwork URL blob for size, not sensitivity', () => {
213. const product = {
214. line_ref: 51206,
215. line_status: 'At Partner Shop',
216. item_name: '10 ft SEG Backdrop',
217. printfile_info: { own_artwork: { PROOF_BACK: 'https://...' } },
218. }
219. const p = projectProduct(product)
220. expect(p.line_status).toBe('At Partner Shop')
221. expect(p).not.toHaveProperty('printfile_info')
222. expect(DROPPED_FIELDS.artwork).toContain('printfile_info')
223. })
224. })
226. describe('rate limit', () => {
227. it('throttles below what Plinth enforces', () => {
228. const perWindow = PLINTH_RATE_LIMIT.refillPerSecond * PLINTH_RATE_LIMIT.documentedLimit.perSeconds
229. expect(perWindow).toBe(9)
230. expect(perWindow).toBeLessThan(PLINTH_RATE_LIMIT.documentedLimit.requests)
231. })
233. it('bursts no higher than the sustained window allows', () => {
234. expect(PLINTH_RATE_LIMIT.capacity).toBeLessThan(PLINTH_RATE_LIMIT.documentedLimit.requests)
235. })
237. it('is slow enough that a fan-out design would be unusable', () => {
238. // 300 per-order detail calls would take ~5.6 minutes. This test exists to
239. // make that concrete: page in bulk, never fan out.
240. const secondsFor300 = 300 / PLINTH_RATE_LIMIT.refillPerSecond
241. expect(secondsFor300).toBeGreaterThan(300)
242. })
244. it('is fast enough for a paged sweep inside a 15-minute cron', () => {
245. const secondsFor12Calls = 12 / PLINTH_RATE_LIMIT.refillPerSecond
246. expect(secondsFor12Calls).toBeLessThan(30)
247. })
248. })