@johntalton/http-util 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# http-util
+
+Set of utilities to aid in building from-scratch [node:http2](https://nodejs.org/docs/latest/api/http2.html) stream compatible services.
+
+- Header parsers
+- Stream Response methods
+- Body parser
+
+## Header Parsers
+### From Client:
+- Accept Encoding - `parse` and `select` based on server/client values
+- Accept Language - `parse` and `select`
+- Accept - `parse` and `select`
+
+- Content Type - returns structured data object for use with Body/etc
+- Forwarded - `parse` with select-right-most helper
+- Multipart - parse into `FormData`
+- Content Disposition - for use inside of Multipart
+
+### Server Sent:
+- Rate Limit
+- Server Timing
+
+## Response
+
+All responders take in a `stream` as well as a metadata object to hint on servername and origin strings etc.
+
+- `sendError` - 500
+- `sendPreflight` - Response to OPTIONS with CORS headers
+- `sendUnauthorized` - Unauthorized
+- `sendNotFound` - 404
+- `sendTooManyRequests` - Rate limit response (429)
+- `sendJSON_Encoded` - Standard Ok response with encoding
+- `sendSSE` - SSE header (leave the `stream` open)
+
+Responses allow for optional CORS headers as well as Server Timing meta data.
+
+## Body
+
+The `requestBody` method returns a `fetch`-like response.  Including methods `blob`, `arrayBuffer`, `bytes`, `text`, `formData`, `json` as well as a `body` as a `ReadableStream`.
+
+The return is a deferred response that does NOT consume the `steam` until calling one of the above methods.
+
+Optional `byteLimit`, `contentLength` and `contentType` can be provided to hint the parser, as well as a `AbortSignal` to abandoned the reader.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@johntalton/http-util",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./headers": "./src/index.js",
+    "./body": "./src/body.js",
+    "./response": "./src/handle-stream-util.js"
+  },
+  "files": [
+    "src/*.js"
+  ],
+  "dependencies": {
+    "@johntalton/sse-util": "^1.0.0"
+  }
+}

package/src/accept-encoding.js

@@ -0,0 +1,53 @@
+import { parseAcceptStyleHeader } from './accept-util.js'
+
+/** @import { AcceptStyleItem } from './accept-util.js' */
+
+export const WELL_KNOWN_ENCODINGS = new Map([
+	[ 'gzip, deflate, br, zstd', [ { name: 'gzip' }, { name: 'deflate' }, { name: 'br' }, { name: 'zstd' } ] ],
+	[ 'gzip, deflate, br', [ { name: 'gzip' }, { name: 'deflate' }, { name: 'br' } ] ]
+])
+
+export class AcceptEncoding {
+	/**
+	 * @param {string|undefined} acceptEncodingHeader
+	 */
+	static parse(acceptEncodingHeader) {
+		return parseAcceptStyleHeader(acceptEncodingHeader, WELL_KNOWN_ENCODINGS)
+	}
+
+	/**
+	 * @param {string|undefined} acceptEncodingHeader
+	 * @param {Array<string>} supportedTypes
+	 */
+	static select(acceptEncodingHeader, supportedTypes) {
+		const accepts = AcceptEncoding.parse(acceptEncodingHeader)
+		return this.selectFrom(accepts, supportedTypes)
+	}
+
+	/**
+	 * @param {Array<AcceptStyleItem>} acceptEncodings
+	 * @param {Array<string>} supportedTypes
+	 */
+	static selectFrom(acceptEncodings, supportedTypes) {
+		for(const acceptEncoding of acceptEncodings) {
+			const { name } = acceptEncoding
+			if(supportedTypes.includes(name)) {
+				return name
+			 }
+		}
+
+		return undefined
+	}
+}
+
+
+// console.log(AcceptEncoding.parse(''))
+// console.log(AcceptEncoding.parse(' '))
+// console.log(AcceptEncoding.parse('zstd'))
+// console.log(AcceptEncoding.parse('identity'))
+// console.log(AcceptEncoding.parse('*'))
+// console.log(AcceptEncoding.parse('gzip, deflate, br, zstd'))
+// console.log(AcceptEncoding.parse('br;q=1.0, gzip;q=0.8, *;q=0.1'))
+// console.log(AcceptEncoding.parse('deflate, gzip;q=1.0, *;q=0.5'))
+// console.log(AcceptEncoding.parse('identity;q=0'))
+// console.log(AcceptEncoding.parse('*;q=0'))

package/src/accept-language.js

@@ -0,0 +1,46 @@
+import { parseAcceptStyleHeader } from './accept-util.js'
+
+/**
+ * @import { AcceptStyleItem } from './accept-util.js'
+ */
+
+export const WELL_KNOWN_LANGUAGES = new Map([
+	[ 'en-US,en;q=0.5', [ { name: 'en-US', quality: 1 }, { name: 'en', quality: 0.5 } ] ],
+	[ 'en-US,en;q=0.9', [ { name: 'en-US', quality: 1 }, { name: 'en', quality: 0.9 } ] ]
+])
+
+export class AcceptLanguage {
+	/**
+	 * @param {string|undefined} acceptLanguageHeader
+	 */
+	static parse(acceptLanguageHeader) {
+		return parseAcceptStyleHeader(acceptLanguageHeader, WELL_KNOWN_LANGUAGES)
+	}
+
+	/**
+	 * @param {string|undefined} acceptLanguageHeader
+	 * @param {Array<string>} supportedTypes
+	 */
+	static select(acceptLanguageHeader, supportedTypes) {
+		const accepts = AcceptLanguage.parse(acceptLanguageHeader)
+		return this.selectFrom(accepts, supportedTypes)
+	}
+
+	/**
+	 * @param {Array<AcceptStyleItem>} acceptLanguages
+	 * @param {Array<string>} supportedTypes
+	 */
+	static selectFrom(acceptLanguages, supportedTypes) {
+		for(const acceptLanguage of acceptLanguages) {
+			const { name } = acceptLanguage
+			if(supportedTypes.includes(name)) {
+				return name
+				}
+		}
+
+		return undefined
+	}
+}
+
+// console.log(AcceptLanguage.parse('en-US,en;q=0.9'))
+// console.log(AcceptLanguage.select('foo;q=0.2, bar-BZ', [ 'bang', 'foo' ]))

package/src/accept-util.js

@@ -0,0 +1,55 @@
+export const QUALITY = 'q'
+export const SEPARATOR = {
+	MEDIA_RANGE: ',',
+	PARAMETER: ';',
+	KVP: '='
+}
+
+export const DEFAULT_QUALITY_STRING = '1'
+
+/**
+ * @typedef {Object} AcceptStyleItem
+ * @property {string} name
+ * @property {number|undefined} [quality]
+ * @property {Map<string, string>|undefined} [parameters]
+ */
+
+/**
+ * @param {string|undefined} header
+ * @param {Map<string, Array<AcceptStyleItem>>} [wellKnown]
+ * @returns {Array<AcceptStyleItem>}
+ */
+export function parseAcceptStyleHeader(header, wellKnown) {
+	if(header === undefined) { return [] }
+
+	const wk = wellKnown?.get(header)
+	if(wk !== undefined) { return wk }
+
+	return header
+		.trim()
+			.split(SEPARATOR.MEDIA_RANGE)
+			.map(mediaRange => {
+				const [ name, ...parametersSet ] = mediaRange
+					.trim()
+					.split(SEPARATOR.PARAMETER)
+
+				const parameters = new Map(parametersSet.map(parameter => {
+					const [ key, value ] = parameter.split(SEPARATOR.KVP).map(p => p.trim())
+					return [ key, value ]
+				}))
+
+				if(!parameters.has(QUALITY)) { parameters.set(QUALITY, DEFAULT_QUALITY_STRING) }
+				const quality = parseFloat(parameters.get(QUALITY) ?? DEFAULT_QUALITY_STRING)
+
+				return {
+					name,
+					quality,
+					parameters
+				}
+			})
+			.filter(entry => entry.name !== undefined && entry.name !== '')
+			.sort((entryA, entryB) => {
+				// B - A descending order
+				return entryB.quality - entryA.quality
+			})
+}

package/src/accept.js

@@ -0,0 +1,125 @@
+import { parseAcceptStyleHeader } from './accept-util.js'
+
+/**
+ * @import { AcceptStyleItem } from './accept-util.js'
+ */
+
+/**
+ * @typedef {Object} AcceptExtensionItem
+ * @property {string} mimetype
+ * @property {string} type
+ * @property {string} subtype
+ */
+
+/**
+ * @typedef {AcceptStyleItem & AcceptExtensionItem} AcceptItem
+ */
+
+export const ACCEPT_SEPARATOR = { SUBTYPE: '/' }
+export const ACCEPT_ANY = '*'
+
+export const WELL_KNOWN = new Map([
+	[ '*/*', [ { name: '*/*', quality: 1 } ] ],
+	[ 'application/json', [ { name: 'application/json', quality: 1 } ] ]
+])
+
+export class Accept {
+	/**
+	 * @param {string|undefined} acceptHeader
+	 * @returns {Array<AcceptItem>}
+	 */
+	static parse(acceptHeader) {
+		return parseAcceptStyleHeader(acceptHeader, WELL_KNOWN)
+			.map(({ name, quality, parameters }) => {
+				const [ type, subtype ] = name
+					.split(ACCEPT_SEPARATOR.SUBTYPE)
+					.map(t => t.trim())
+
+				return {
+					mimetype: `${type}${ACCEPT_SEPARATOR.SUBTYPE}${subtype ?? ACCEPT_ANY}`,
+					name, type, subtype,
+					quality,
+					parameters
+				}
+			})
+			.sort((entryA, entryB) => {
+				if(entryA.quality === entryB.quality) {
+					// prefer things with less ANY
+					const specificityA = (entryA.type === ACCEPT_ANY ? 1 : 0) + (entryA.subtype === ACCEPT_ANY ? 1 : 0)
+					const specificityB = (entryB.type === ACCEPT_ANY ? 1 : 0) + (entryB.subtype === ACCEPT_ANY ? 1 : 0)
+					return specificityA - specificityB
+				}
+
+				// B - A descending order
+				const qualityB = entryB.quality ?? 0
+				const qualityA = entryA.quality ?? 0
+				return qualityB - qualityA
+				// return entryB.quality - entryA.quality
+			})
+	}
+
+	/**
+	 * @param {string|undefined} acceptHeader
+	 * @param {Array<string>} supportedTypes
+	 */
+	static select(acceptHeader, supportedTypes) {
+		const accepts = Accept.parse(acceptHeader)
+		return this.selectFrom(accepts, supportedTypes)
+	}
+
+	/**
+	 * @param {Array<AcceptItem>} accepts
+	 * @param {Array<string>} supportedTypes
+	 */
+	static selectFrom(accepts, supportedTypes) {
+		const bests = accepts.map(accept => {
+			const { type, subtype, quality } = accept
+			const st = supportedTypes.filter(supportedType => {
+				const [ stType, stSubtype ] = supportedType.split(ACCEPT_SEPARATOR.SUBTYPE)
+				return ((stType === type || type === ACCEPT_ANY) && (stSubtype === subtype || subtype === ACCEPT_ANY))
+			})
+
+			return {
+				supportedTypes: st,
+				quality
+			}
+		})
+		.filter(best => {
+			return best.supportedTypes.length > 0
+		})
+
+		if(bests.length === 0) { return undefined }
+		const [ first ] = bests
+		if(first === undefined) { return undefined }
+		const [ firstSt ] = first.supportedTypes
+		return firstSt
+	}
+}
+
+// console.log(Accept.parse('text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, text/*;q=.8, */*;q=0.7'))
+// console.log(Accept.select('text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, text/*;q=.8, */*;q=0.7', [ 'application/json', 'text/plain' ]))
+
+// const tests = [
+// 	undefined,
+// 	'',
+// 	'	',
+// 	' fake',
+// 	'    application/json',
+// 	' application/xml,',
+// 	' ,application/xml   ,,',
+// 	' audio/*; q=0.2, audio/basic',
+// 	' text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8',
+// 	' text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed,\ntext/plain;format=fixed;q=0.4, */*;q=0.5',
+
+// 	' */*, foo/bar, foo/*, biz/bang, */*;q=.2, quix/quak;q=.1',
+// 	'foo / bar ; q = .5'
+// ]
+
+// tests.forEach(test => {
+// 	const result = Accept.parse(test)
+// 	console.log('=============================')
+// 	console.log({ test })
+// 	console.log('---')
+// 	console.log(result)
+// })
+

package/src/body.js

@@ -0,0 +1,320 @@
+import { CHARSET_UTF8, MIME_TYPE_MULTIPART_FORM_DATA, MIME_TYPE_URL_FORM_DATA } from './content-type.js'
+import { Multipart } from './multipart.js'
+
+export const DEFAULT_BYTE_LIMIT = 1024 * 1024 //
+
+/**
+ * @import { Readable } from 'node:stream'
+ */
+
+/**
+ * @import { ContentType } from './content-type.js'
+ */
+
+/**
+ * @typedef {Object} BodyOptions
+ * @property {AbortSignal} [signal]
+ * @property {number} [byteLimit]
+ * @property {number} [contentLength]
+ * @property {ContentType|undefined} [contentType]
+ */
+
+/**
+ * @typedef {Object} BodyFuture
+ * @property {number} duration
+ * @property {ReadableStream} body
+ * @property {ContentType|undefined} contentType
+ * @property { (mimetype: string) => Promise<Blob> } blob
+ * @property { () => Promise<ArrayBufferLike> } arrayBuffer
+ * @property { () => Promise<Uint8Array> } bytes
+ * @property { () => Promise<string> } text
+ * @property { () => Promise<FormData>} formData
+ * @property { () => Promise<any> } json
+ */
+
+
+/**
+ * @param {Readable} stream
+ * @param {BodyOptions} [options]
+ * @returns {BodyFuture}
+ */
+export function requestBody(stream, options) {
+	const signal = options?.signal
+	const byteLimit = options?.byteLimit ?? DEFAULT_BYTE_LIMIT
+	const contentLength = options?.contentLength
+	const charset = options?.contentType?.charset ?? CHARSET_UTF8
+	const contentType = options?.contentType
+
+	const invalidContentLength = (contentLength === undefined || isNaN(contentLength))
+	// if(contentLength > byteLimit) {
+		// console.log(contentLength, invalidContentLength)
+	// 	throw new Error('contentLength exceeds limit')
+	// }
+
+	// console.log('closed/errored', stream.closed, stream.errored)
+	// console.log('readable length', stream.readableLength)
+	// console.log('readable/ended', stream.readable, stream.readableEnded)
+
+	const stats = {
+		byteLength: 0,
+		closed: false,
+		duration: 0
+	}
+
+	// console.log('create body reader, underlying source')
+
+	/** @type {UnderlyingDefaultSource} */
+	const underlyingSource = {
+		start(controller) {
+			// console.log('body reader start')
+
+			if(invalidContentLength) {
+				// console.log('invalid content length')
+
+				// stats.closed = true
+				// controller.close()
+				// return
+			}
+
+			if(contentLength === 0) {
+				// console.log('zero content length')
+
+				stats.closed = true
+				controller.close()
+				return
+			}
+
+			if(stream.readableLength === 0) {
+				// console.log('body has zero bytes')
+
+				// stats.closed = true
+				// controller.close()
+				// return
+			}
+
+
+			const listener = () => {
+				controller.error(new Error('Abort Signal Timed out'))
+			}
+
+			signal?.addEventListener('abort', listener, { once: true })
+
+			stream.on('data', chunk => {
+				if(signal?.aborted) {
+					console.log('body reader aborted')
+					controller.error(new Error('Chunk read Abort Signal Timed out'))
+					stats.closed = true
+					return
+				}
+
+				if(stats.closed) {
+					console.log('late chunk already closed')
+					stats.closed = true
+					return
+				}
+
+				// chunk is a node Buffer (which is a TypedArray)
+				if(!ArrayBuffer.isView(chunk)) {
+					controller.error('invalid chunk type')
+					stats.closed = true
+				}
+
+				stats.byteLength += chunk.byteLength
+
+				if(stats.byteLength > byteLimit) {
+					console.log('body exceed byte limit', stats.byteLength)
+					controller.error(new Error('body exceed byte limit'))
+					// stream.close()
+					stats.closed = true
+					return
+				}
+
+				// console.log('body reader chunk', stats.byteLength)
+				controller.enqueue(chunk)
+			})
+
+			stream.on('end', () => {
+				// console.log('body reader end')
+				signal?.removeEventListener('abort', listener)
+
+				if(!stats.closed) {
+					// console.log('body reader close controller on end')
+					stats.closed = true
+					controller.close()
+				}
+			})
+
+			stream.on('close', () => {
+				// console.log('body reader stream close')
+				if(!stats.closed) {
+					stats.closed = true
+					controller.close()
+				}
+			})
+			stream.on('aborted', () => console.log('body reader stream aborted'))
+		},
+
+		cancel(reason) {
+			console.log('body reader canceled', reason)
+		}
+	}
+
+	/**
+	 * @returns {ReadableStream}
+	 */
+	function makeReader() {
+		if(stats.closed) { throw new Error('body already consumed') }
+		// console.log('makeReader')
+		return new ReadableStream(underlyingSource)
+	}
+
+	/**
+	 * @template T
+	 * @param {(reader: ReadableStream) => Promise<T>} futureFn
+	 */
+	async function wrap(futureFn) {
+		const start = performance.now()
+		const reader = makeReader()
+		// console.log(reader)
+		const result = await futureFn(reader)
+		// console.log(result)
+		const end = performance.now()
+		const duration = end - start
+		stats.duration = duration
+		return result
+	}
+
+	return {
+		get duration() { return stats.duration },
+		get body() { return makeReader() },
+		get contentType() { return contentType },
+
+		blob: (/** @type {string | undefined} */ mimetype) => wrap(reader => bodyBlob(reader, mimetype ?? contentType?.mimetype)),
+		arrayBuffer: () => wrap(reader => bodyArrayBuffer(reader)),
+		bytes: () => wrap(reader => bodyUint8Array(reader)),
+		text: () => wrap(reader => bodyText(reader, charset)),
+		formData: () => wrap(reader => bodyFormData(reader, contentType)),
+		json: () => wrap(reader => bodyJSON(reader, charset))
+	}
+}
+
+/**
+ * @param {ReadableStream} reader
+ * @param {string} [mimetype]
+ */
+export async function bodyBlob(reader, mimetype) {
+	const parts = []
+	for await (const part of reader) {
+		// console.log('push part', part.length)
+		parts.push(part)
+	}
+
+	// console.log('Blob')
+	return new Blob(parts, { type: mimetype ?? '' })
+}
+
+/**
+ * @param {ReadableStream} reader
+ */
+export async function bodyArrayBuffer(reader) {
+	const blob = await bodyBlob(reader)
+	return blob.arrayBuffer()
+
+	// const u8 = await bodyUint8Array(reader)
+	// return u8.buffer
+}
+
+/**
+ * @param {ReadableStream} reader
+ */
+export async function bodyUint8Array(reader) {
+	const buffer = await bodyArrayBuffer(reader)
+	return new Uint8Array(buffer)
+
+	// let total = 0
+	// const parts = []
+	// for await (const part of reader) {
+	// 	total += part.byteLength
+	// 	parts.push(part)
+	// }
+
+	// const buffer = new Uint8Array(total)
+	// let offset = 0
+	// for (const part of parts) {
+	// 	buffer.set(part, offset)
+	// 	offset += part.byteLength
+	// }
+
+	// return buffer
+}
+
+/**
+ * @param {ReadableStream} reader
+ * @param {string} [charset]
+ */
+export async function bodyText(reader, charset) {
+	// const blob = await bodyBlob(reader)
+	// return blob.text()
+
+	const u8 = await bodyUint8Array(reader)
+	const decoder = new TextDecoder(charset ?? CHARSET_UTF8, { fatal: true })
+	return decoder.decode(u8)
+}
+
+/**
+ * @param {ReadableStream} reader
+ * @param {string} [charset]
+ */
+export async function bodyJSON(reader, charset) {
+	// console.log('bodyJSON')
+	const text = await bodyText(reader, charset)
+	return (text === '') ? {} : JSON.parse(text)
+}
+
+/**
+ * @param {ReadableStream} reader
+ * @param {ContentType} contentType
+ */
+async function _bodyFormData_Multipart(reader, contentType) {
+	const MULTIPART_FORM_DATA_BOUNDARY_PARAMETER = 'boundary'
+
+	const text = await bodyText(reader, contentType.charset)
+	const boundary = contentType.parameters.get(MULTIPART_FORM_DATA_BOUNDARY_PARAMETER)
+	if(boundary === undefined) { throw new Error('unspecified boundary') }
+
+	return Multipart.parse(text, boundary, contentType.charset)
+}
+
+/**
+ * @param {ReadableStream} reader
+ * @param {ContentType} contentType
+ */
+async function _bodyFormData_URL(reader, contentType) {
+	const text = await bodyText(reader, contentType.charset)
+	const sp = new URLSearchParams(text)
+	const formData = new FormData()
+
+	for(const [ key, value ] of sp.entries()) {
+		formData.append(key, value)
+	}
+
+	return formData
+}
+
+/**
+ * @param {ReadableStream} reader
+ * @param {ContentType|undefined} contentType
+ */
+export async function bodyFormData(reader, contentType) {
+	if(contentType === undefined) { throw new Error('undefined content type for form data') }
+
+	if(contentType.mimetype === MIME_TYPE_MULTIPART_FORM_DATA) {
+		return _bodyFormData_Multipart(reader, contentType)
+	}
+
+	if(contentType.mimetype === MIME_TYPE_URL_FORM_DATA) {
+		return _bodyFormData_URL(reader, contentType)
+	}
+
+	throw new TypeError('unknown mime type for form data')
+}