)['view']
- assertEquals(ctx.getState(Core.Handler.stateKeys.view) !== undefined, true)
-})
-
-Deno.test('Context#state does not expose framework-wired internal keys', () => {
- const ctx = createTestContext()
- ctx[Core.InternalContext].setInternalState(Core.Handler.stateKeys.setSession, async () => {})
- ctx[Core.InternalContext].setInternalState(Core.Handler.stateKeys.session, { userId: '1' })
- assertEquals(typeof ctx.getState(Core.Handler.stateKeys.setSession), 'function')
- assertEquals(ctx.getState(Core.Handler.stateKeys.session)?.['userId'], '1')
- assertEquals(Object.hasOwn(ctx.state, 'setSession'), false)
- assertEquals(Object.hasOwn(ctx.state, 'session'), false)
-})
-
-Deno.test('Context#state exposes a live mutable record (documented API)', () => {
- const ctx = createTestContext()
- assertEquals(typeof ctx.state, 'object')
- ctx.state['foo'] = 'bar'
- assertEquals(ctx.state['foo'], 'bar')
-})
-
-Deno.test('Context#streamRender throws Deno.errors.NotSupported', async () => {
- const ctx = createTestContext('http://localhost/')
- let thrown = false
- try {
- await ctx.streamRender('hello.dve')
+ ctx.send.json({}, { status: 999 as 200 })
} catch (e) {
- thrown = true
- assertEquals(e instanceof Deno.errors.NotSupported, true)
- }
- assertEquals(thrown, true)
-})
-
-Deno.test('Context#streamRender throws when view engine not configured', async () => {
- const ctx = createTestContext('http://localhost/')
- let thrown = false
- try {
- await ctx.streamRender('hello.dve')
- } catch (e) {
- thrown = true
- assertEquals((e as Error).message.includes('View engine not configured'), true)
+ threw = true
+ assertEquals(e instanceof Deno.errors.InvalidData, true)
}
- assertEquals(thrown, true)
+ assertEquals(threw, true)
})
-Deno.test('Context#text reads body as string', async () => {
- const ctx = createTestContext('http://localhost/', {}, { method: 'POST', body: 'plain text' })
- const text = await ctx.text()
- assertEquals(text, 'plain text')
+Deno.test('Context send.text builds a text response', async () => {
+ const ctx = Helper.createTestContext()
+ const res = ctx.send.text('hello')
+ assertEquals(await res.text(), 'hello')
+ assertEquals(res.headers.get('content-type'), 'text/plain; charset=utf-8')
})
-Deno.test('Context#text returns cached on second call', async () => {
- const ctx = createTestContext('http://localhost/', {}, { method: 'POST', body: 'cached' })
- const first = await ctx.text()
- const second = await ctx.text()
- assertEquals(first, second)
+Deno.test('Context set.header and set.cookie reflect in response', () => {
+ const ctx = Helper.createTestContext()
+ ctx.set.header('x-a', '1').cookie('sid', 'abc')
+ const res = ctx.send.text('x')
+ assertEquals(res.headers.get('x-a'), '1')
+ assertEquals(res.headers.get('set-cookie')?.startsWith('sid=abc'), true)
})
-Deno.test('Context#text then arrayBuffer throws already consumed', async () => {
- const ctx = createTestContext('http://localhost/', {}, { method: 'POST', body: 'data' })
- await ctx.text()
- let thrown = false
+Deno.test('Context set.session write throws without session middleware', async () => {
+ const ctx = Helper.createTestContext()
+ let threw = false
try {
- await ctx.arrayBuffer()
+ await ctx.set.session({ id: 1 })
} catch (e) {
- thrown = true
- assertEquals((e as Error).message, 'Request body already consumed')
+ threw = true
+ assertEquals(e instanceof Deno.errors.NotSupported, true)
}
- assertEquals(thrown, true)
+ assertEquals(threw, true)
})
-Deno.test('Context#url returns request url', () => {
- const ctx = createTestContext('http://localhost/items?q=1')
- assertEquals(ctx.url, 'http://localhost/items?q=1')
+Deno.test('Context setParams decodes percent-encoded values', () => {
+ const ctx = Helper.createTestContext('http://localhost/')
+ Core.Context.internalOf(ctx).setParams({ name: 'a%20b' })
+ assertEquals(ctx.get.param('name'), 'a b')
})
diff --git a/tests/core/Response.test.ts b/tests/core/Response.test.ts
deleted file mode 100644
index dfbd065..0000000
--- a/tests/core/Response.test.ts
+++ /dev/null
@@ -1,398 +0,0 @@
-import { assertEquals, assertThrows } from '@std/assert'
-import { fileURLToPath } from 'node:url'
-import * as Core from '@core/index.ts'
-
-const baseHeaders = { 'X-App': 'test' }
-const buildRedirect = (url: string, status: number): globalThis.Response =>
- new globalThis.Response(null, { status, headers: new Headers({ Location: url }) })
-const send = Core.Response.create(baseHeaders, [], buildRedirect)
-
-Deno.test('Response#create accepts valid 2xx-5xx and null-body statuses across send helpers', () => {
- assertEquals(send.json({ ok: true }, { status: 200 }).status, 200)
- assertEquals(send.text('x', { status: 599 }).status, 599)
- assertEquals(send.html('x', { status: 404 }).status, 404)
- assertEquals(send.custom('x', { status: 201 }).status, 201)
- assertEquals(send.json({ ok: true }, { status: 204 }).status, 204)
-})
-
-Deno.test('Response#create custom drops the body for a no-content status', async () => {
- const res = send.custom('ignored', { status: 204 })
- assertEquals(res.status, 204)
- assertEquals(res.body, null)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create custom includes Set-Cookie values', () => {
- const cookieSend = Core.Response.create({}, ['a=1; Path=/', 'b=2; Path=/'], buildRedirect)
- const res = cookieSend.custom('body', { status: 200 })
- const setCookies = res.headers.getSetCookie()
- assertEquals(setCookies.length, 2)
-})
-
-Deno.test('Response#create custom merges base headers and options', async () => {
- const res = send.custom('body', { status: 201, headers: { 'X-Custom': 'y' } })
- assertEquals(res.status, 201)
- assertEquals(res.headers.get('X-App'), 'test')
- assertEquals(res.headers.get('X-Custom'), 'y')
- assertEquals(await res.text(), 'body')
-})
-
-Deno.test('Response#create custom options.headers overrides base', () => {
- const res = send.custom(null, { headers: { 'X-App': 'override' } })
- assertEquals(res.headers.get('X-App'), 'override')
-})
-
-Deno.test('Response#create custom with Headers instance merges correctly', () => {
- const res = send.custom(null, { headers: new Headers({ 'X-Test': 'yes' }) })
- assertEquals(res.headers.get('X-App'), 'test')
- assertEquals(res.headers.get('X-Test'), 'yes')
-})
-
-Deno.test('Response#create custom with array headers merges correctly', () => {
- const headers: [string, string][] = [['X-Arr', 'val']]
- const res = send.custom(null, { headers })
- assertEquals(res.headers.get('X-App'), 'test')
- assertEquals(res.headers.get('X-Arr'), 'val')
-})
-
-Deno.test('Response#create custom with no body returns empty response', async () => {
- const res = send.custom(null, { status: 204 })
- assertEquals(res.status, 204)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create custom with null body and no options', async () => {
- const res = send.custom(null)
- assertEquals(res.status, 200)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create data drops the body and length for a no-content status', async () => {
- const res = send.data('bytes', 'file.txt', { status: 204 }, 'text/plain')
- assertEquals(res.status, 204)
- assertEquals(res.body, null)
- assertEquals(res.headers.get('Content-Length'), null)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create data encodes non-ASCII filename via RFC 6266 filename*', () => {
- const res = send.data(new TextEncoder().encode('x'), 'résumé-日本.pdf')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(res.status, 200)
- assertEquals(cd.includes("filename*=UTF-8''"), true)
- assertEquals(cd.includes(encodeURIComponent('résumé-日本.pdf')), true)
- assertEquals(cd.includes('filename="r_sum_-__.pdf"'), true)
-})
-
-Deno.test('Response#create data escapes a backslash path separator from filename', () => {
- const res = send.data(new TextEncoder().encode('x'), 'a\\b.txt')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd, 'attachment; filename="b.txt"')
-})
-
-Deno.test('Response#create data escapes quotes in filename', () => {
- const res = send.data(new TextEncoder().encode('x'), 'file"name.txt')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd.includes('\\"'), true)
- assertEquals(cd.includes('filename'), true)
-})
-
-Deno.test('Response#create data omits filename* for pure-ASCII filename', () => {
- const res = send.data(new TextEncoder().encode('x'), 'plain.txt')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd, 'attachment; filename="plain.txt"')
- assertEquals(cd.includes('filename*'), false)
-})
-
-Deno.test('Response#create data sets Content-Disposition and Content-Type', () => {
- const res = send.data(new TextEncoder().encode('data'), 'file.bin', undefined, 'application/pdf')
- assertEquals(res.headers.get('Content-Type'), 'application/pdf')
- assertEquals(res.headers.get('Content-Disposition'), 'attachment; filename="file.bin"')
- assertEquals(res.headers.get('Content-Length'), '4')
- assertEquals(res.headers.get('X-App'), 'test')
-})
-
-Deno.test('Response#create data string sets Content-Length', () => {
- const res = send.data('hello', 'a.txt')
- assertEquals(res.headers.get('Content-Length'), '5')
- assertEquals(res.headers.get('Content-Disposition'), 'attachment; filename="a.txt"')
-})
-
-Deno.test('Response#create data strips DEL character from filename', () => {
- const res = send.data(new TextEncoder().encode('x'), 'file\x7Fname.txt')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd.includes('\x7F'), false)
-})
-
-Deno.test('Response#create data strips control characters from filename', () => {
- const res = send.data(new TextEncoder().encode('x'), 'file\x00name\x1F.txt')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd.includes('\x00'), false)
- assertEquals(cd.includes('\x1F'), false)
- assertEquals(cd.includes('filename.txt'), true)
-})
-
-Deno.test('Response#create data strips path separators from filename', () => {
- const res = send.data(new TextEncoder().encode('x'), '../../etc/passwd')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd.includes('..'), false)
- assertEquals(cd.includes('passwd'), true)
-})
-
-Deno.test('Response#create data with Uint8Array sets Content-Length', () => {
- const data = new TextEncoder().encode('hello')
- const res = send.data(data, 'file.bin')
- assertEquals(res.headers.get('Content-Length'), '5')
-})
-
-Deno.test('Response#create data with a non-ASCII name escapes quotes in the ASCII fallback', () => {
- const res = send.data(new TextEncoder().encode('x'), '发"票.pdf')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd.includes('filename="_\\"_.pdf"'), true)
- assertEquals(cd.includes(`filename*=UTF-8''${encodeURIComponent('发"票.pdf')}`), true)
-})
-
-Deno.test('Response#create data with default content-type uses octet-stream', () => {
- const res = send.data('hello', 'a.txt')
- assertEquals(res.headers.get('Content-Type'), 'application/octet-stream')
-})
-
-Deno.test('Response#create data with empty Uint8Array', () => {
- const res = send.data(new Uint8Array(0), 'empty.bin')
- assertEquals(res.headers.get('Content-Length'), '0')
- assertEquals(res.headers.get('Content-Disposition'), 'attachment; filename="empty.bin"')
-})
-
-Deno.test('Response#create file reads file and sets headers', async () => {
- const filePath = fileURLToPath(import.meta.resolve('@tests/fixtures/response-file.txt'))
- const res = await send.file(filePath, 'custom.txt')
- assertEquals(res.headers.get('Content-Disposition'), 'attachment; filename="custom.txt"')
- assertEquals(res.headers.get('Content-Type'), 'application/octet-stream')
- assertEquals(await res.text(), 'fixture content\n')
-})
-
-Deno.test('Response#create file with a non-ASCII filename emits an RFC 6266 filename* parameter', async () => {
- const filePath = fileURLToPath(import.meta.resolve('@tests/fixtures/response-file.txt'))
- const res = await send.file(filePath, '发票-résumé.pdf')
- const cd = res.headers.get('Content-Disposition') ?? ''
- assertEquals(cd.includes('filename="__-r_sum_.pdf"'), true)
- assertEquals(cd.includes(`filename*=UTF-8''${encodeURIComponent('发票-résumé.pdf')}`), true)
- await res.body?.cancel()
-})
-
-Deno.test('Response#create file with missing path throws', async () => {
- let thrown = false
- try {
- await send.file('/nonexistent/path/file.txt')
- } catch (e) {
- thrown = true
- assertEquals((e as globalThis.Error).message.includes('Failed to read file'), true)
- }
- assertEquals(thrown, true)
-})
-
-Deno.test('Response#create file with no custom filename uses path basename', async () => {
- const filePath = fileURLToPath(import.meta.resolve('@tests/fixtures/response-file.txt'))
- const res = await send.file(filePath)
- assertEquals(res.headers.get('Content-Disposition'), 'attachment; filename="response-file.txt"')
- assertEquals(await res.text(), 'fixture content\n')
-})
-
-Deno.test('Response#create helper Content-Type wins over a generic context Content-Type', async () => {
- const ctxHeaders = { 'Content-Type': 'application/xml', 'X-Req': '1' }
- const sendCtx = Core.Response.create(ctxHeaders, [], buildRedirect)
- const jsonRes = sendCtx.json({ ok: true })
- assertEquals(jsonRes.headers.get('Content-Type'), 'application/json')
- assertEquals(jsonRes.headers.get('X-Req'), '1')
- assertEquals(await jsonRes.json(), { ok: true })
- assertEquals(sendCtx.text('hi').headers.get('Content-Type'), 'text/plain; charset=utf-8')
- assertEquals(sendCtx.html('x').headers.get('Content-Type'), 'text/html; charset=utf-8')
-})
-
-Deno.test('Response#create html drops the body for a reset-content status', async () => {
- const res = send.html('ignored', { status: 205 })
- assertEquals(res.status, 205)
- assertEquals(res.body, null)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create html includes Set-Cookie values', () => {
- const cookieSend = Core.Response.create({}, ['sid=xyz'], buildRedirect)
- const res = cookieSend.html('ok
')
- assertEquals(res.headers.getSetCookie().length, 1)
-})
-
-Deno.test('Response#create html sets text/html', async () => {
- const res = send.html('hi
', { status: 200 })
- assertEquals(res.headers.get('Content-Type'), 'text/html; charset=utf-8')
- assertEquals(await res.text(), 'hi
')
-})
-
-Deno.test('Response#create html with empty string', async () => {
- const res = send.html('')
- assertEquals(res.status, 200)
- assertEquals(res.headers.get('Content-Type'), 'text/html; charset=utf-8')
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create html with large content', async () => {
- const largeHtml = '' + 'x'.repeat(10000) + '
'
- const res = send.html(largeHtml)
- assertEquals(res.headers.get('Content-Type'), 'text/html; charset=utf-8')
- assertEquals(await res.text(), largeHtml)
-})
-
-Deno.test('Response#create json drops the body for a no-content status', async () => {
- const res = send.json({ ignored: true }, { status: 204 })
- assertEquals(res.status, 204)
- assertEquals(res.body, null)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create json includes Set-Cookie values', () => {
- const cookieSend = Core.Response.create({}, ['token=abc'], buildRedirect)
- const res = cookieSend.json({ ok: true })
- assertEquals(res.headers.getSetCookie().length, 1)
-})
-
-Deno.test('Response#create json serializes and sets application/json', async () => {
- const res = send.json({ a: 1 }, { status: 200 })
- assertEquals(res.headers.get('Content-Type'), 'application/json')
- assertEquals(await res.json(), { a: 1 })
-})
-
-Deno.test('Response#create json with array value', async () => {
- const res = send.json([1, 2, 3])
- assertEquals(res.status, 200)
- assertEquals(res.headers.get('Content-Type'), 'application/json')
- assertEquals(await res.json(), [1, 2, 3])
-})
-
-Deno.test('Response#create json with nested object', async () => {
- const res = send.json({ nested: { array: [1, 2, 3] } })
- assertEquals(res.headers.get('Content-Type'), 'application/json')
- const body = await res.json()
- assertEquals(body, { nested: { array: [1, 2, 3] } })
-})
-
-Deno.test('Response#create json with null value', async () => {
- const res = send.json(null)
- assertEquals(res.status, 200)
- assertEquals(res.headers.get('Content-Type'), 'application/json')
- assertEquals(await res.text(), 'null')
-})
-
-Deno.test('Response#create json with number value', async () => {
- const res = send.json(42)
- assertEquals(res.status, 200)
- assertEquals(res.headers.get('Content-Type'), 'application/json')
- assertEquals(await res.json(), 42)
-})
-
-Deno.test('Response#create keeps the body for an ordinary status', async () => {
- const res = send.json({ ok: true }, { status: 200 })
- assertEquals(res.status, 200)
- assertEquals(await res.json(), { ok: true })
-})
-
-Deno.test('Response#create per-call Content-Type override still wins over the helper default', () => {
- const res = send.json({ a: 1 }, { headers: { 'Content-Type': 'text/plain' } })
- assertEquals(res.headers.get('Content-Type'), 'text/plain')
-})
-
-Deno.test('Response#create redirect defaults to 302', () => {
- const res = send.redirect('https://example.com/')
- assertEquals(res.status, 302)
- assertEquals(res.headers.get('Location'), 'https://example.com/')
-})
-
-Deno.test('Response#create redirect delegates to buildRedirect', () => {
- const res = send.redirect('https://example.com/', 301)
- assertEquals(res.status, 301)
- assertEquals(res.headers.get('Location'), 'https://example.com/')
-})
-
-Deno.test('Response#create redirect with 308', () => {
- const res = send.redirect('https://example.com/', 308)
- assertEquals(res.status, 308)
- assertEquals(res.headers.get('Location'), 'https://example.com/')
-})
-
-Deno.test('Response#create rejects an out-of-range or non-integer status before the constructor throws', () => {
- for (
- const status of [99, 100, 199, 600, 1000, 0, -1, Number.NaN, 3.5, Number.POSITIVE_INFINITY]
- ) {
- assertThrows(
- () => send.json({ ok: true }, { status }),
- Deno.errors.InvalidData,
- '200-599'
- )
- }
-})
-
-Deno.test('Response#create stream drops the body for a no-content status', () => {
- const res = send.stream(new ReadableStream(), { status: 204 })
- assertEquals(res.status, 204)
- assertEquals(res.body, null)
-})
-
-Deno.test('Response#create stream sets Content-Type', () => {
- const stream = new ReadableStream({
- start(controller) {
- controller.enqueue(new TextEncoder().encode('x'))
- controller.close()
- }
- })
- const res = send.stream(stream, undefined, 'text/plain')
- assertEquals(res.headers.get('Content-Type'), 'text/plain')
- assertEquals(res.headers.get('X-App'), 'test')
-})
-
-Deno.test('Response#create stream with custom options', () => {
- const stream = new ReadableStream({
- start(controller) {
- controller.enqueue(new TextEncoder().encode('data'))
- controller.close()
- }
- })
- const res = send.stream(stream, { status: 201 }, 'text/event-stream')
- assertEquals(res.status, 201)
- assertEquals(res.headers.get('Content-Type'), 'text/event-stream')
- assertEquals(res.headers.get('X-App'), 'test')
-})
-
-Deno.test('Response#create stream with default contentType uses octet-stream', () => {
- const stream = new ReadableStream({
- start(controller) {
- controller.enqueue(new TextEncoder().encode('data'))
- controller.close()
- }
- })
- const res = send.stream(stream)
- assertEquals(res.headers.get('Content-Type'), 'application/octet-stream')
-})
-
-Deno.test('Response#create text drops the body for a not-modified status', async () => {
- const res = send.text('ignored', { status: 304 })
- assertEquals(res.status, 304)
- assertEquals(res.body, null)
- assertEquals(await res.text(), '')
-})
-
-Deno.test('Response#create text includes Set-Cookie values', () => {
- const cookieSend = Core.Response.create({}, ['x=1'], buildRedirect)
- const res = cookieSend.text('hello')
- assertEquals(res.headers.getSetCookie().length, 1)
-})
-
-Deno.test('Response#create text sets text/plain', async () => {
- const res = send.text('hello', { status: 200 })
- assertEquals(res.headers.get('Content-Type'), 'text/plain; charset=utf-8')
- assertEquals(await res.text(), 'hello')
-})
-
-Deno.test('Response#create text with empty string', async () => {
- const res = send.text('')
- assertEquals(res.headers.get('Content-Type'), 'text/plain; charset=utf-8')
- assertEquals(await res.text(), '')
-})
diff --git a/tests/helper.ts b/tests/helper.ts
new file mode 100644
index 0000000..9e4ed1a
--- /dev/null
+++ b/tests/helper.ts
@@ -0,0 +1,15 @@
+import * as Core from '@core/index.ts'
+
+export default class Helper {
+ static createTestContext(
+ url = 'http://localhost/',
+ requestInit?: RequestInit
+ ): Core.Context {
+ const request = new Request(url, requestInit)
+ return new Core.Context(request, new URL(url), null, undefined, undefined, null, () => {})
+ }
+
+ static okNext(): Promise {
+ return Promise.resolve(new Response('ok'))
+ }
+}
From 23de156423755bb2713ced8935ba76ebc2e51e98 Mon Sep 17 00:00:00 2001
From: NeaByteLab <209737579+NeaByteLab@users.noreply.github.com>
Date: Thu, 25 Jun 2026 22:14:42 +0700
Subject: [PATCH 07/40] refactor(core): simplify Handler errors and trim
Constant tables
- Add contentDisposition and control-char stripping to Handler
- Drop validation-reason plumbing from error response builders
- Rename isErrorWithStatus to isStatusError and accept a cause
- Restructure securityHeaders into header and default entries
- Trim content-type table and remove render budget constants
- Remove obsolete error, hardening, and helper test suites
---
src/core/Constant.ts | 324 ++++++++++-------------------
src/core/Handler.ts | 316 +++++++++++++----------------
tests/config/HumanError.test.ts | 62 ------
tests/core/Constant.test.ts | 85 +++++---
tests/core/Error.test.ts | 347 --------------------------------
tests/core/Handler.test.ts | 173 ++++++----------
tests/core/Hardening.test.ts | 78 -------
tests/core/Helper.test.ts | 60 ------
8 files changed, 360 insertions(+), 1085 deletions(-)
delete mode 100644 tests/config/HumanError.test.ts
delete mode 100644 tests/core/Error.test.ts
delete mode 100644 tests/core/Hardening.test.ts
delete mode 100644 tests/core/Helper.test.ts
diff --git a/src/core/Constant.ts b/src/core/Constant.ts
index 236e9f4..dd112da 100644
--- a/src/core/Constant.ts
+++ b/src/core/Constant.ts
@@ -1,16 +1,44 @@
import type * as Types from '@interfaces/index.ts'
-import * as Core from '@core/index.ts'
/**
- * Shared constants and framework singletons.
- * @description Centralizes all static data: encoders, regexes, defaults, maps.
+ * Framework wide constant values.
+ * @description Holds shared defaults, regexes, and lookup tables.
*/
export class Constant {
- /** Shared UTF-8 text decoder */
- static readonly decoder: TextDecoder = new Core.API.TextDecoder()
- /** Shared UTF-8 text encoder */
- static readonly encoder: TextEncoder = new Core.API.TextEncoder()
- /** HTML entity map for escaping */
+ /** Regex trimming leading and trailing spaces */
+ static readonly cookieTrimRegex = /^[ \t]+|[ \t]+$/g
+ /** Shared UTF-8 text decoder instance */
+ static readonly decoder: TextDecoder = new TextDecoder()
+ /** Default content type for unknown files */
+ static readonly defaultContentType = 'application/octet-stream'
+ /** Default worker pool size */
+ static readonly defaultPoolSize = 4
+ /** Default queue depth multiplier per worker */
+ static readonly defaultQueueFactor = 8
+ /** Default queue wait timeout in milliseconds */
+ static readonly defaultQueueWaitMs = 2000
+ /** Default session cookie option values */
+ static readonly defaultSessionOptions: Readonly = {
+ name: 'session',
+ httpOnly: true,
+ maxAge: 86400,
+ path: '/',
+ sameSite: 'Lax',
+ secure: false
+ }
+ /** Default worker task timeout in milliseconds */
+ static readonly defaultWorkerTaskTimeoutMs = 5000
+ /** Regex escaping disposition filename characters */
+ static readonly dispositionEscapeRegex = /[\\"]/g
+ /** Regex matching non-ASCII disposition characters */
+ static readonly dispositionNonAsciiRegex = /[\u0080-\u{10FFFF}]/u
+ /** Regex stripping directory path prefix */
+ static readonly dispositionPathRegex = /^.*[\\/]/
+ /** Template file extension for views */
+ static readonly dveExtension = '.dve'
+ /** Shared UTF-8 text encoder instance */
+ static readonly encoder: TextEncoder = new TextEncoder()
+ /** HTML entity replacements for escaping */
static readonly htmlEscapeMap: Readonly = {
'&': '&',
'<': '<',
@@ -18,70 +46,66 @@ export class Constant {
'"': '"',
"'": '''
}
- /** Matches characters needing HTML escaping */
+ /** Regex matching characters needing HTML escape */
static readonly htmlEscapeRegex = /[&<>"']/g
- /** Strips separators and control characters */
- static readonly sanitizeRegex = /^.*[\\/]|\p{Cc}/gu
- /** Matches backslash or double-quote characters */
- static readonly escapeRegex = /[\\\"]/g
- /** Matches any non-ASCII character */
- static readonly nonAsciiRegex = /[\u0080-\u{10FFFF}]/u
- /** Matches all non-ASCII characters globally */
- static readonly nonAsciiGlobalRegex = /[\u0080-\u{10FFFF}]/gu
- /** Dotted path regex for fast-path */
- static readonly simplePathRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/
- /** Matches leading and trailing cookie whitespace */
- static readonly cookieTrimRegex = /^[ \t]+|[ \t]+$/g
- /** DVE template file extension */
- static readonly dveExtension = '.dve'
- /** Default worker pool size */
- static readonly defaultPoolSize = 4
- /** Default worker task timeout in ms */
- static readonly defaultWorkerTaskTimeoutMs = 5_000
- /** Default pending-task multiplier per worker slot */
- static readonly defaultQueueFactor = 8
- /** Default projected-wait deadline in ms */
- static readonly defaultQueueWaitMs = 2_000
- /** Null-body HTTP status codes */
- static readonly nullBodyStatuses: ReadonlySet = new Set([101, 204, 205, 304])
- /** Valid redirect status codes */
- static readonly redirectStatuses: ReadonlySet = new Set([301, 302, 303, 307, 308])
- /** Default max route parameter length */
+ /** Maximum allowed route parameter length */
static readonly maxParamLength = 1024
- /** Default max request URL length */
+ /** Maximum allowed request URL length */
static readonly maxUrlLength = 8192
- /** Default max #each iterations */
- static readonly defaultMaxIterations = 100_000
- /** Default max #each body executions per render */
- static readonly defaultMaxRenderIterations = 1_000_000
- /** Default max output characters per render */
- static readonly defaultMaxOutputSize = 5_000_000
- /** Maximum template include nesting depth */
- static readonly maxIncludeDepth = 64
- /** Route watcher debounce in milliseconds */
+ /** Status codes that forbid response bodies */
+ static readonly nullBodyStatuses: ReadonlySet = new Set([101, 204, 205, 304])
+ /** Content type for problem detail responses */
+ static readonly problemJsonContentType = 'application/problem+json'
+ /** Status codes treated as HTTP redirects */
+ static readonly redirectStatuses: ReadonlySet = new Set([301, 302, 303, 307, 308])
+ /** Route reload debounce in milliseconds */
static readonly routeDebounceMs = 150
- /** Template watcher debounce in milliseconds */
+ /** Template reload debounce in milliseconds */
static readonly templateDebounceMs = 100
- /** Default session cookie options */
- static readonly defaultSessionOptions: Types.SessionCookieOpts = {
- cookieName: 'session',
- maxAge: 86400,
- path: '/',
- sameSite: 'Lax',
- httpOnly: true,
- secure: true
+ /** Allowed route module file extensions */
+ static readonly allowedExtensions: readonly string[] = ['cjs', 'js', 'jsx', 'mjs', 'ts', 'tsx']
+ /** File extension to content type map */
+ static readonly contentTypes: Readonly = {
+ css: 'text/css; charset=utf-8',
+ csv: 'text/csv; charset=utf-8',
+ gif: 'image/gif',
+ htm: 'text/html; charset=utf-8',
+ html: 'text/html; charset=utf-8',
+ ico: 'image/x-icon',
+ jpeg: 'image/jpeg',
+ jpg: 'image/jpeg',
+ js: 'text/javascript; charset=utf-8',
+ json: 'application/json; charset=utf-8',
+ map: 'application/json; charset=utf-8',
+ mjs: 'text/javascript; charset=utf-8',
+ pdf: 'application/pdf',
+ png: 'image/png',
+ svg: 'image/svg+xml; charset=utf-8',
+ txt: 'text/plain; charset=utf-8',
+ wasm: 'application/wasm',
+ webp: 'image/webp',
+ woff: 'font/woff',
+ woff2: 'font/woff2',
+ xml: 'application/xml; charset=utf-8'
}
- /** Problem details JSON content type */
- static readonly problemJsonContentType = 'application/problem+json'
- /** Status code to error message */
- static readonly serverErrorMessages: Readonly<
- Partial>
- > = {
+ /** Supported HTTP request methods */
+ static readonly httpMethods: readonly Types.HttpMethod[] = [
+ 'DELETE',
+ 'GET',
+ 'HEAD',
+ 'OPTIONS',
+ 'PATCH',
+ 'POST',
+ 'PUT'
+ ]
+ /** Status code to reason phrase map */
+ static readonly serverErrorMessages: Readonly>> = {
400: 'Bad Request',
401: 'Unauthorized',
403: 'Forbidden',
404: 'Not Found',
405: 'Method Not Allowed',
+ 406: 'Not Acceptable',
408: 'Request Timeout',
409: 'Conflict',
410: 'Gone',
@@ -96,166 +120,22 @@ export class Constant {
503: 'Service Unavailable',
504: 'Gateway Timeout'
}
- /** Secure default values for security headers */
- static readonly securityHeaderDefaults: Readonly = {
- 'Cross-Origin-Opener-Policy': 'same-origin',
- 'Cross-Origin-Resource-Policy': 'same-origin',
- 'Origin-Agent-Cluster': '?1',
- 'Referrer-Policy': 'no-referrer',
- 'X-Content-Type-Options': 'nosniff',
- 'X-DNS-Prefetch-Control': 'off',
- 'X-Download-Options': 'noopen',
- 'X-Frame-Options': 'SAMEORIGIN',
- 'X-Permitted-Cross-Domain-Policies': 'none'
- }
- /** File extensions allowed for route modules */
- static readonly allowedExtensions: readonly Types.RouteFileExtension[] = [
- 'cjs',
- 'js',
- 'jsx',
- 'mjs',
- 'ts',
- 'tsx'
- ]
- /** Extension to MIME type map */
- static readonly contentTypes: Readonly = {
- html: 'text/html',
- htm: 'text/html',
- css: 'text/css',
- less: 'text/css',
- scss: 'text/css',
- sass: 'text/css',
- js: 'application/javascript',
- mjs: 'application/javascript',
- cjs: 'application/javascript',
- ts: 'application/typescript',
- tsx: 'application/typescript',
- jsx: 'application/javascript',
- json: 'application/json',
- jsonld: 'application/ld+json',
- ndjson: 'application/x-ndjson',
- map: 'application/json',
- geojson: 'application/geo+json',
- topojson: 'application/json',
- md: 'text/markdown',
- markdown: 'text/markdown',
- sh: 'application/x-sh',
- csh: 'application/x-csh',
- bash: 'text/plain',
- php: 'application/x-httpd-php',
- yaml: 'text/yaml',
- yml: 'text/yaml',
- toml: 'text/toml',
- ics: 'text/calendar',
- png: 'image/png',
- jpg: 'image/jpeg',
- jpeg: 'image/jpeg',
- gif: 'image/gif',
- webp: 'image/webp',
- svg: 'image/svg+xml',
- ico: 'image/x-icon',
- avif: 'image/avif',
- apng: 'image/apng',
- heif: 'image/heif',
- heic: 'image/heic',
- bmp: 'image/bmp',
- tiff: 'image/tiff',
- tif: 'image/tiff',
- ttf: 'font/ttf',
- otf: 'font/otf',
- woff: 'font/woff',
- woff2: 'font/woff2',
- ttc: 'font/collection',
- eot: 'application/vnd.ms-fontobject',
- pdf: 'application/pdf',
- epub: 'application/epub+zip',
- azw: 'application/vnd.amazon.ebook',
- doc: 'application/msword',
- docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
- xls: 'application/vnd.ms-excel',
- xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
- ppt: 'application/vnd.ms-powerpoint',
- pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
- odt: 'application/vnd.oasis.opendocument.text',
- ods: 'application/vnd.oasis.opendocument.spreadsheet',
- odp: 'application/vnd.oasis.opendocument.presentation',
- vsd: 'application/vnd.visio',
- mpkg: 'application/vnd.apple.installer+xml',
- xml: 'application/xml',
- xhtml: 'application/xhtml+xml',
- xul: 'application/vnd.mozilla.xul+xml',
- csv: 'text/csv',
- txt: 'text/plain',
- rtf: 'application/rtf',
- abw: 'application/x-abiword',
- bin: 'application/octet-stream',
- zip: 'application/zip',
- tar: 'application/x-tar',
- gz: 'application/gzip',
- bz: 'application/x-bzip',
- bz2: 'application/x-bzip2',
- xz: 'application/x-xz',
- rar: 'application/vnd.rar',
- arc: 'application/x-freearc',
- jar: 'application/java-archive',
- '7z': 'application/x-7z-compressed',
- mp4: 'video/mp4',
- m4v: 'video/mp4',
- mpeg: 'video/mpeg',
- webm: 'video/webm',
- avi: 'video/x-msvideo',
- mov: 'video/quicktime',
- mkv: 'video/x-matroska',
- wmv: 'video/x-ms-wmv',
- flv: 'video/x-flv',
- ogv: 'video/ogg',
- ogx: 'application/ogg',
- '3gp': 'video/3gpp',
- '3g2': 'video/3gpp2',
- mts: 'video/mp2t',
- mp3: 'audio/mpeg',
- ogg: 'audio/ogg',
- oga: 'audio/ogg',
- wav: 'audio/wav',
- flac: 'audio/flac',
- aac: 'audio/aac',
- m4a: 'audio/mp4',
- opus: 'audio/opus',
- weba: 'audio/webm',
- mid: 'audio/midi',
- midi: 'audio/midi',
- cda: 'application/x-cdf',
- glb: 'model/gltf-binary',
- gltf: 'model/gltf+json',
- wasm: 'application/wasm',
- manifest: 'application/manifest+json',
- webmanifest: 'application/manifest+json',
- serviceworker: 'application/javascript'
- }
- /** Security header option to name */
+ /** Security header names with default values */
static readonly securityHeaders = {
- contentSecurityPolicy: 'Content-Security-Policy',
- crossOriginEmbedderPolicy: 'Cross-Origin-Embedder-Policy',
- crossOriginOpenerPolicy: 'Cross-Origin-Opener-Policy',
- crossOriginResourcePolicy: 'Cross-Origin-Resource-Policy',
- originAgentCluster: 'Origin-Agent-Cluster',
- referrerPolicy: 'Referrer-Policy',
- strictTransportSecurity: 'Strict-Transport-Security',
- xContentTypeOptions: 'X-Content-Type-Options',
- xDnsPrefetchControl: 'X-DNS-Prefetch-Control',
- xDownloadOptions: 'X-Download-Options',
- xFrameOptions: 'X-Frame-Options',
- xPermittedCrossDomainPolicies: 'X-Permitted-Cross-Domain-Policies',
- xPoweredBy: 'X-Powered-By'
- } as const satisfies Types.StringRecord
- /** HTTP methods used for route registration */
- static readonly httpMethods: readonly Types.HttpMethod[] = [
- 'DELETE',
- 'GET',
- 'HEAD',
- 'OPTIONS',
- 'PATCH',
- 'POST',
- 'PUT'
- ]
+ contentSecurityPolicy: { header: 'Content-Security-Policy', default: null },
+ crossOriginEmbedderPolicy: { header: 'Cross-Origin-Embedder-Policy', default: null },
+ crossOriginOpenerPolicy: { header: 'Cross-Origin-Opener-Policy', default: 'same-origin' },
+ crossOriginResourcePolicy: { header: 'Cross-Origin-Resource-Policy', default: 'same-origin' },
+ originAgentCluster: { header: 'Origin-Agent-Cluster', default: '?1' },
+ referrerPolicy: { header: 'Referrer-Policy', default: 'no-referrer' },
+ strictTransportSecurity: { header: 'Strict-Transport-Security', default: null },
+ xContentTypeOptions: { header: 'X-Content-Type-Options', default: 'nosniff' },
+ xDnsPrefetchControl: { header: 'X-DNS-Prefetch-Control', default: 'off' },
+ xDownloadOptions: { header: 'X-Download-Options', default: 'noopen' },
+ xFrameOptions: { header: 'X-Frame-Options', default: 'SAMEORIGIN' },
+ xPermittedCrossDomainPolicies: {
+ header: 'X-Permitted-Cross-Domain-Policies',
+ default: 'none'
+ }
+ } as const
}
diff --git a/src/core/Handler.ts b/src/core/Handler.ts
index 8e506f7..dc2fa3d 100644
--- a/src/core/Handler.ts
+++ b/src/core/Handler.ts
@@ -1,36 +1,16 @@
import type * as Types from '@interfaces/index.ts'
-import type { Context } from '@core/Context.ts'
import * as Core from '@core/index.ts'
/**
- * Handler utilities for routing layers.
- * @description Static helpers used by routing, middleware, and context layers.
+ * HTTP error and header helpers.
+ * @description Builds error responses, headers, and status errors.
*/
export class Handler {
- /** Well-known framework state keys */
- static readonly stateKeys: Types.StateKeysMap = {
- view: Handler.stateKey('view'),
- worker: Handler.stateKey('worker'),
- session: Handler.stateKey('session'),
- setSession: Handler.stateKey<(data: Types.DataRecord) => Promise>('setSession'),
- clearSession: Handler.stateKey<() => void>('clearSession'),
- validated: Handler.stateKey('validated')
- } as const
- /** Reserved framework state key names, not writable by public setState */
- static readonly reservedStateKeys: ReadonlySet = new Set([
- 'view',
- 'worker',
- 'session',
- 'setSession',
- 'clearSession',
- 'validated'
- ])
-
/**
- * Append Set-Cookie values to headers.
- * @description Appends each cookie value as a Set-Cookie header.
- * @param headers - Target Headers instance
- * @param cookieValues - Cookie values to append
+ * Append Set-Cookie header values.
+ * @description Adds each cookie value as separate header.
+ * @param headers - Headers instance to mutate
+ * @param cookieValues - Cookie header strings to append
*/
static appendCookies(headers: Headers, cookieValues: readonly string[]): void {
for (const cookieValue of cookieValues) {
@@ -39,13 +19,13 @@ export class Handler {
}
/**
- * Assert a value is a positive finite number.
- * @description Single validator for positive-number construction options.
- * @param value - Value to validate
- * @param label - Option name surfaced in the error message
- * @param unit - Optional unit suffix, e.g. "milliseconds"
- * @returns The validated positive finite number
- * @throws {Deno.errors.InvalidData} When the value is non-finite or <= 0
+ * Assert value is positive finite.
+ * @description Throws labeled error when value is invalid.
+ * @param value - Number value to validate
+ * @param label - Label used in error message
+ * @param unit - Optional unit used in message
+ * @returns Same value when valid
+ * @throws When value is not positive finite
*/
static assertPositiveFinite(value: number, label: string, unit?: string): number {
if (!Number.isFinite(value) || value <= 0) {
@@ -58,25 +38,25 @@ export class Handler {
}
/**
- * Build error response with format.
- * @description Tries middleware then JSON or HTML, masks error messages.
- * @param ctx - Request context
- * @param statusCode - HTTP status code
- * @param error - Thrown error
- * @param errorMiddleware - Optional custom handler
- * @returns Error response
+ * Build error response with middleware.
+ * @description Uses middleware response when valid otherwise default.
+ * @param ctx - Request context instance
+ * @param statusCode - HTTP status code to send
+ * @param error - Caught error instance
+ * @param errorMiddleware - Optional error middleware handler
+ * @returns Promise resolving to error response
*/
static async buildResponse(
- ctx: Context,
+ ctx: Core.Context,
statusCode: number,
error: globalThis.Error,
errorMiddleware: Types.ErrorMiddleware | null
): Promise {
if (errorMiddleware) {
const customResponse = await errorMiddleware(ctx, {
- url: ctx.url,
- method: ctx.request.method,
- pathname: ctx.pathname,
+ url: ctx.get.url().href,
+ method: ctx.get.method(),
+ pathname: ctx.get.pathname(),
statusCode,
error
})
@@ -88,14 +68,43 @@ export class Handler {
}
/**
- * Create StatusError with status code.
- * @description Produces Error with immutable statusCode property attached.
- * @param statusCode - HTTP status code
- * @param message - Error message
- * @returns Error with statusCode property
+ * Build content disposition header value.
+ * @description Sanitizes filename and adds UTF-8 fallback.
+ * @param filename - Download filename to encode
+ * @returns Content-Disposition header value
+ */
+ static contentDisposition(filename: string): string {
+ const baseName = filename.replace(Core.Constant.dispositionPathRegex, '')
+ const safeName = Handler.stripControlChars(baseName) || 'download'
+ const asciiName = Array.from(safeName, (char) => char.codePointAt(0)! > 127 ? '_' : char).join(
+ ''
+ )
+ .replace(Core.Constant.dispositionEscapeRegex, (match) => `\\${match}`)
+ const asciiFallback = asciiName || 'download'
+ let headerValue = `attachment; filename="${asciiFallback}"`
+ if (Core.Constant.dispositionNonAsciiRegex.test(safeName)) {
+ headerValue += `; filename*=UTF-8''${encodeURIComponent(safeName)}`
+ }
+ return headerValue
+ }
+
+ /**
+ * Create error with status code.
+ * @description Attaches non-writable status code property.
+ * @param statusCode - HTTP status code to attach
+ * @param message - Error message text
+ * @param cause - Optional cause detail strings
+ * @returns Error carrying status code
*/
- static createStatusError(statusCode: number, message: string): Types.StatusError {
- const error = new Error(message) as Types.StatusError
+ static createStatusError(
+ statusCode: number,
+ message: string,
+ cause?: readonly string[]
+ ): Types.StatusError {
+ const error =
+ (cause === undefined
+ ? new Error(message)
+ : new Error(message, { cause })) as Types.StatusError
Object.defineProperty(error, 'statusCode', {
value: statusCode,
writable: false,
@@ -106,11 +115,11 @@ export class Handler {
}
/**
- * Minimal HTML error page.
- * @description Returns simple HTML with status and escaped message.
- * @param statusCode - Status code and title
- * @param message - Escaped message body
- * @returns HTML string
+ * Build default error HTML page.
+ * @description Escapes message into simple HTML document.
+ * @param statusCode - HTTP status code to show
+ * @param message - Error message text
+ * @returns HTML error page string
*/
static defaultErrorHtml(statusCode: number, message: string): string {
const escapedMessage = Handler.escapeHtml(message)
@@ -126,49 +135,48 @@ export class Handler {
}
/**
- * Build error response by Accept header.
- * @description Single source of truth for safe error responses.
- * @param ctx - Request context
- * @param statusCode - HTTP status code
- * @returns Error response with masked message
+ * Build negotiated error response.
+ * @description Sends JSON or HTML based on accept.
+ * @param ctx - Request context instance
+ * @param statusCode - HTTP status code to send
+ * @returns Negotiated error response
*/
- static errorResponse(ctx: Context, statusCode: number): globalThis.Response {
+ static errorResponse(ctx: Core.Context, statusCode: number): globalThis.Response {
const errorMessage = Handler.safeMessage(statusCode)
- const wantsJson = Handler.wantsJson(ctx.request.headers)
- const reasons = Handler.safeReasons(ctx[Core.InternalContext].getFrameworkError())
+ const wantsJson = Handler.wantsJson(ctx.get.request().headers)
try {
if (wantsJson) {
- return ctx.send.json(Handler.problemDetails(statusCode, ctx.pathname, undefined, reasons), {
- status: statusCode,
+ return ctx.send.json(Handler.problemDetails(statusCode, ctx.get.pathname()), {
+ status: statusCode as Types.HttpStatusCode,
headers: { 'Content-Type': Core.Constant.problemJsonContentType }
})
}
return ctx.send.html(Handler.defaultErrorHtml(statusCode, errorMessage), {
- status: statusCode
+ status: statusCode as Types.HttpStatusCode
})
} catch {
- return Handler.safeFallbackResponse(ctx, statusCode, errorMessage, wantsJson, reasons)
+ return Handler.negotiatedResponse(statusCode, errorMessage, wantsJson, ctx.get.pathname())
}
}
/**
* Escape HTML special characters.
- * @description Replaces &, <, >, ", ' with HTML entities.
- * @param text - Raw string
- * @returns Escaped string safe for HTML content
+ * @description Replaces unsafe characters with HTML entities.
+ * @param text - Text to escape
+ * @returns Escaped HTML safe text
*/
static escapeHtml(text: string): string {
return text.replace(Core.Constant.htmlEscapeRegex, (ch) => Core.Constant.htmlEscapeMap[ch]!)
}
/**
- * Extract status code from error.
- * @description Prefers statusCode property, then Deno error class, else 500.
- * @param error - Unknown value from catch block
- * @returns Object with statusCode and Error instance
+ * Extract status and error value.
+ * @description Maps Deno errors to HTTP status codes.
+ * @param error - Unknown thrown value
+ * @returns Status code and error pair
*/
static extractError(error: unknown): Types.ExtractedError {
- if (Handler.isErrorWithStatus(error)) {
+ if (Handler.isStatusError(error)) {
return { statusCode: error.statusCode, error }
}
if (error instanceof Error) {
@@ -178,53 +186,52 @@ export class Handler {
}
/**
- * Check path is existing directory.
- * @description Returns false when path is missing or not directory.
- * @param resolvedDir - Absolute directory path
- * @returns True when the path exists and is a directory
+ * Check path is a directory.
+ * @description Returns false when stat call fails.
+ * @param path - Filesystem path to check
+ * @returns True when path is directory
*/
- static isDirectory(resolvedDir: string): boolean {
+ static isDirectory(path: string): boolean {
try {
- return Deno.statSync(resolvedDir).isDirectory
+ return Deno.statSync(path).isDirectory
} catch {
return false
}
}
/**
- * Narrow a value to a status-bearing Error.
- * @description True for Errors whose statusCode is 400-599.
- * @param value - Unknown value from a catch block
- * @returns True when value is an Error with an in-range statusCode
+ * Check value carries HTTP status.
+ * @description Validates error with status in client range.
+ * @param value - Unknown value to inspect
+ * @returns True when value is status error
*/
- static isErrorWithStatus(value: unknown): value is Types.StatusError {
+ static isStatusError(value: unknown): value is Types.StatusError {
if (!(value instanceof Error) || !('statusCode' in value)) {
return false
}
- const statusValue = (value as Types.StatusCodeCarrier).statusCode
+ const statusValue = (value as Types.StatusCarrier).statusCode
return typeof statusValue === 'number' && statusValue >= 400 && statusValue < 600
}
/**
- * Build a content-negotiated error response.
- * @description Single site for JSON or HTML error bodies.
- * @param statusCode - HTTP status code to emit
- * @param message - Safe masked message
- * @param wantsJson - Whether the client prefers JSON
- * @param pathname - Optional request pathname included in JSON bodies
- * @returns Error response with security headers and the negotiated body
+ * Build response without context helpers.
+ * @description Produces JSON or HTML error directly.
+ * @param statusCode - HTTP status code to send
+ * @param message - Error message text
+ * @param wantsJson - Send JSON when true
+ * @param pathname - Optional request path instance
+ * @returns Negotiated error response
*/
static negotiatedResponse(
statusCode: number,
message: string,
wantsJson: boolean,
- pathname?: string,
- reasons?: readonly string[]
+ pathname?: string
): globalThis.Response {
- const headers = new Core.API.Headers(Core.Constant.securityHeaderDefaults)
+ const headers = new Core.API.Headers()
if (wantsJson) {
headers.set('Content-Type', Core.Constant.problemJsonContentType)
- const body = Handler.problemDetails(statusCode, pathname, message, reasons)
+ const body = Handler.problemDetails(statusCode, pathname, message)
return new Core.API.Response(Core.API.jsonStringify(body), { status: statusCode, headers })
}
headers.set('Content-Type', 'text/html; charset=utf-8')
@@ -235,36 +242,31 @@ export class Handler {
}
/**
- * Build structured error problem details.
- * @description Returns problem body with type, title, status, optional instance.
- * @param statusCode - HTTP status code
- * @param pathname - Optional request pathname as instance
- * @param title - Optional title overriding safe message
- * @param reasons - Optional validation reasons added as errors
- * @returns Problem details object
+ * Build problem details object.
+ * @description Includes instance path when provided.
+ * @param statusCode - HTTP status code to report
+ * @param pathname - Optional instance path value
+ * @param title - Optional problem title text
+ * @returns Problem details payload object
*/
static problemDetails(
statusCode: number,
pathname?: string,
- title?: string,
- reasons?: readonly string[]
+ title?: string
): Types.ProblemDetails {
const base: Types.ProblemDetails = {
type: 'about:blank',
title: title ?? Handler.safeMessage(statusCode),
status: statusCode
}
- const withInstance = pathname === undefined ? base : { ...base, instance: pathname }
- return reasons !== undefined && reasons.length > 0
- ? { ...withInstance, errors: reasons }
- : withInstance
+ return pathname === undefined ? base : { ...base, instance: pathname }
}
/**
- * Resolve safe message for status.
- * @description Returns known message or generic fallback for status.
- * @param statusCode - HTTP status code
- * @returns Safe user-facing error message
+ * Resolve safe status message text.
+ * @description Falls back by client or server range.
+ * @param statusCode - HTTP status code to map
+ * @returns Reason phrase for status
*/
static safeMessage(statusCode: number): string {
return (
@@ -274,42 +276,27 @@ export class Handler {
}
/**
- * Extract safe reasons from error.
- * @description Returns string causes only for 422 status errors.
- * @param error - Error to inspect, or null
- * @returns Reason strings, or undefined when none
+ * Strip control characters from text.
+ * @description Removes characters below 32 and delete.
+ * @param text - Text to sanitize
+ * @returns Text without control characters
*/
- static safeReasons(error: Error | null): readonly string[] | undefined {
- if (
- error === null ||
- !Handler.isErrorWithStatus(error) ||
- error.statusCode !== 422 ||
- !Array.isArray(error.cause)
- ) {
- return undefined
+ static stripControlChars(text: string): string {
+ let result = ''
+ for (const char of text) {
+ const code = char.codePointAt(0)!
+ if (code >= 32 && code !== 127) {
+ result += char
+ }
}
- const reasons = (error.cause as readonly unknown[]).filter(
- (reason): reason is string => typeof reason === 'string'
- )
- return reasons.length > 0 ? reasons : undefined
+ return result
}
/**
- * Create a branded state key.
- * @description Returns type-branded string for compile-time safety.
- * @template T - The value type this key maps to
- * @param key - Raw string key
- * @returns Branded StateKey
- */
- static stateKey(key: string): Types.StateKey {
- return key as Types.StateKey
- }
-
- /**
- * Convert HeadersInit to record.
- * @description Returns plain string record from any HeadersInit variant.
- * @param init - Headers, array, or object
- * @returns Key-value string record
+ * Convert headers init to record.
+ * @description Normalizes Headers, array, or object input.
+ * @param init - Optional headers init value
+ * @returns String record of header pairs
*/
static toRecord(init?: HeadersInit): Types.StringRecord {
if (!init) {
@@ -325,10 +312,10 @@ export class Handler {
}
/**
- * Check client prefers JSON response.
- * @description Returns true when Accept header includes application/json.
- * @param headers - Request headers
- * @returns True when JSON is preferred
+ * Check accept header wants JSON.
+ * @description Detects JSON or problem JSON accept values.
+ * @param headers - Request headers instance
+ * @returns True when client accepts JSON
*/
static wantsJson(headers: Headers): boolean {
const accept = headers.get('accept')
@@ -339,10 +326,10 @@ export class Handler {
}
/**
- * Map standard error class to status.
- * @description Whitelists unambiguous Deno error types, else returns 500.
- * @param error - Error instance to classify
- * @returns Canonical HTTP status code
+ * Map Deno error to status.
+ * @description Returns specific code or 500 default.
+ * @param error - Error instance to inspect
+ * @returns HTTP status code for error
*/
private static denoErrorStatus(error: Error): number {
if (error instanceof Deno.errors.NotFound) {
@@ -365,23 +352,4 @@ export class Handler {
}
return 500
}
-
- /**
- * Build a guaranteed-valid error response.
- * @description Emits baseline security headers when send path fails.
- * @param ctx - Request context
- * @param statusCode - HTTP status code
- * @param message - Safe masked message
- * @param wantsJson - Whether client prefers JSON
- * @returns Safe error response
- */
- private static safeFallbackResponse(
- ctx: Context,
- statusCode: number,
- message: string,
- wantsJson: boolean,
- reasons?: readonly string[]
- ): globalThis.Response {
- return Handler.negotiatedResponse(statusCode, message, wantsJson, ctx.pathname, reasons)
- }
}
diff --git a/tests/config/HumanError.test.ts b/tests/config/HumanError.test.ts
deleted file mode 100644
index 0643536..0000000
--- a/tests/config/HumanError.test.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import { assertEquals, assertThrows } from '@std/assert'
-import * as Core from '@core/index.ts'
-import * as Middleware from '@middleware/index.ts'
-import * as Routing from '@routing/index.ts'
-
-const echoWorkerUrl = import.meta.resolve('@tests/fixtures/echo_worker.ts')
-
-Deno.test('BodyLimit with limit 0 is rejected at creation', () => {
- assertThrows(
- () => Middleware.Mware.bodyLimit({ limit: 0 }),
- Deno.errors.InvalidData,
- 'positive finite'
- )
-})
-
-Deno.test('BodyLimit with negative limit is rejected at creation', () => {
- assertThrows(
- () => Middleware.Mware.bodyLimit({ limit: -1 }),
- Deno.errors.InvalidData,
- 'positive finite'
- )
-})
-
-Deno.test('Router constructor accepts poolSize 0 as 1', async () => {
- const router = new Routing.Router({
- routesDir: './routes',
- worker: { scriptURL: echoWorkerUrl, poolSize: 0 }
- })
- const handler = (router as unknown as { handler: unknown }).handler as {
- workerPool?: Core.Worker
- }
- assertEquals(handler.workerPool !== undefined, true)
- try {
- const result = await handler.workerPool!.run('ok')
- assertEquals(result, 'ok')
- } finally {
- handler.workerPool!.terminate()
- }
-})
-
-Deno.test('Router constructor throws on invalid worker config', () => {
- assertThrows(() => {
- new Routing.Router({
- routesDir: './routes',
- worker: { scriptURL: 'not-a-valid-worker-specifier', poolSize: 1 }
- })
- })
-})
-
-Deno.test('Worker#createPool with poolSize 0 creates working pool', async () => {
- const pool = Core.Worker.createPool({ scriptURL: echoWorkerUrl, poolSize: 0 })
- try {
- const result = await pool.run('hello')
- assertEquals(result, 'hello')
- } finally {
- pool.terminate()
- }
-})
-
-Deno.test('Worker#createPool with poolSize 0 uses 1', () => {
- assertThrows(() => Core.Worker.createPool({ scriptURL: 'not-a-valid-worker-specifier' }))
-})
diff --git a/tests/core/Constant.test.ts b/tests/core/Constant.test.ts
index de68980..1a61bc1 100644
--- a/tests/core/Constant.test.ts
+++ b/tests/core/Constant.test.ts
@@ -1,35 +1,60 @@
import { assertEquals } from '@std/assert'
import * as Core from '@core/index.ts'
-Deno.test('Constant#allowedExtensions contains expected route extensions', () => {
- assertEquals(Core.Constant.allowedExtensions.includes('ts'), true)
- assertEquals(Core.Constant.allowedExtensions.includes('tsx'), true)
- assertEquals(Core.Constant.allowedExtensions.includes('js'), true)
- assertEquals(Core.Constant.allowedExtensions.includes('jsx'), true)
- assertEquals(Core.Constant.allowedExtensions.includes('mjs'), true)
- assertEquals(Core.Constant.allowedExtensions.includes('cjs'), true)
- assertEquals(Core.Constant.allowedExtensions.length, 6)
-})
-
-Deno.test('Constant#contentTypes has common MIME types', () => {
- assertEquals(Core.Constant.contentTypes['html'], 'text/html')
- assertEquals(Core.Constant.contentTypes['json'], 'application/json')
+Deno.test('Constant content types map known extensions', () => {
+ assertEquals(Core.Constant.contentTypes['html'], 'text/html; charset=utf-8')
+ assertEquals(Core.Constant.contentTypes['css'], 'text/css; charset=utf-8')
assertEquals(Core.Constant.contentTypes['png'], 'image/png')
- assertEquals(Core.Constant.contentTypes['js'], 'application/javascript')
- assertEquals(Core.Constant.contentTypes['txt'], 'text/plain')
- assertEquals(Core.Constant.contentTypes['pdf'], 'application/pdf')
- assertEquals(Core.Constant.contentTypes['css'], 'text/css')
- assertEquals(Core.Constant.contentTypes['svg'], 'image/svg+xml')
-})
-
-Deno.test('Constant#httpMethods contains standard HTTP methods', () => {
- assertEquals(Core.Constant.httpMethods, [
- 'DELETE',
- 'GET',
- 'HEAD',
- 'OPTIONS',
- 'PATCH',
- 'POST',
- 'PUT'
- ])
+ assertEquals(Core.Constant.defaultContentType, 'application/octet-stream')
+})
+
+Deno.test('Constant default session options use safe defaults', () => {
+ assertEquals(Core.Constant.defaultSessionOptions.name, 'session')
+ assertEquals(Core.Constant.defaultSessionOptions.httpOnly, true)
+ assertEquals(Core.Constant.defaultSessionOptions.sameSite, 'Lax')
+})
+
+Deno.test('Constant exposes default numeric limits', () => {
+ assertEquals(Core.Constant.maxUrlLength, 8192)
+ assertEquals(Core.Constant.maxParamLength, 1024)
+ assertEquals(Core.Constant.defaultPoolSize, 4)
+ assertEquals(Core.Constant.defaultQueueFactor, 8)
+ assertEquals(Core.Constant.defaultQueueWaitMs, 2000)
+ assertEquals(Core.Constant.defaultWorkerTaskTimeoutMs, 5000)
+})
+
+Deno.test('Constant html escape map covers unsafe characters', () => {
+ assertEquals(Core.Constant.htmlEscapeMap['&'], '&')
+ assertEquals(Core.Constant.htmlEscapeMap['<'], '<')
+ assertEquals(Core.Constant.htmlEscapeMap['>'], '>')
+ assertEquals(Core.Constant.htmlEscapeMap['"'], '"')
+ assertEquals(Core.Constant.htmlEscapeMap["'"], ''')
+})
+
+Deno.test('Constant http methods include common verbs', () => {
+ assertEquals(Core.Constant.httpMethods.includes('GET'), true)
+ assertEquals(Core.Constant.httpMethods.includes('POST'), true)
+ assertEquals(Core.Constant.httpMethods.includes('DELETE'), true)
+})
+
+Deno.test('Constant null body and redirect status sets', () => {
+ assertEquals(Core.Constant.nullBodyStatuses.has(204), true)
+ assertEquals(Core.Constant.nullBodyStatuses.has(200), false)
+ assertEquals(Core.Constant.redirectStatuses.has(302), true)
+ assertEquals(Core.Constant.redirectStatuses.has(200), false)
+})
+
+Deno.test('Constant security headers carry defaults', () => {
+ assertEquals(Core.Constant.securityHeaders.xContentTypeOptions.default, 'nosniff')
+ assertEquals(Core.Constant.securityHeaders.xFrameOptions.default, 'SAMEORIGIN')
+})
+
+Deno.test('Constant server error messages map status codes', () => {
+ assertEquals(Core.Constant.serverErrorMessages[404], 'Not Found')
+ assertEquals(Core.Constant.serverErrorMessages[500], 'Internal Server Error')
+})
+
+Deno.test('Constant shared encoder and decoder are usable', () => {
+ const bytes = Core.Constant.encoder.encode('hi')
+ assertEquals(Core.Constant.decoder.decode(bytes), 'hi')
})
diff --git a/tests/core/Error.test.ts b/tests/core/Error.test.ts
deleted file mode 100644
index 7576010..0000000
--- a/tests/core/Error.test.ts
+++ /dev/null
@@ -1,347 +0,0 @@
-import { assertEquals } from '@std/assert'
-import * as Core from '@core/index.ts'
-
-Deno.test('Error#buildResponse 500 does not leak error message', async () => {
- const request = new Request('http://localhost/', {
- headers: new Headers({ Accept: 'application/json' })
- })
- const ctx = new Core.Context(request, new URL('http://localhost/'), {})
- const res = await Core.Handler.buildResponse(
- ctx,
- 500,
- new globalThis.Error('Connection to ************************ failed'),
- null
- )
- const body = (await res.json()) as { title: string }
- assertEquals(body.title, 'Internal Server Error')
- assertEquals(JSON.stringify(body).includes('password'), false)
-})
-
-Deno.test('Error#buildResponse HTML output escapes message content', async () => {
- const request = new Request('http://localhost/')
- const ctx = new Core.Context(request, new URL('http://localhost/'), {})
- const res = await Core.Handler.buildResponse(ctx, 404, new globalThis.Error('irrelevant'), null)
- const html = await res.text()
- assertEquals(html.includes('