@johntalton/http-util 2.0.0 → 2.0.3

package/README.md

@@ -16,29 +16,89 @@ Set of utilities to aid in building from-scratch [node:http2](https://nodejs.org
 - Forwarded - `parse` with select-right-most helper
 - Multipart - parse into `FormData`
 - Content Disposition - for use inside of Multipart
+- Conditionals - Etag / FixDate for IfMatch, IfModifiedSince etc
 
 ### Server Sent:
 - Rate Limit
 - Server Timing
 
+
+```javascript
+import {
+  Accept,
+  MIME_TYPE_JSON,
+  MIME_TYPE_TEXT
+} from '@johntalton/http-util/headers'
+
+// assuming our path/method/server supports content in json or text
+const supportedType = [ MIME_TYPE_JSON, MIME_TYPE_TEXT ]
+
+// from request.header.accept (client prefers json)
+const acceptHeader = 'application/json;q=.5, */*;q.4'
+
+const bestMatchingType = Accept.select(acceptHeader, supportedType)
+// bestMatchingType === 'application/json'
+```
+
 ## Response
 
 All responders take in a `stream` as well as a metadata object to hint on servername and origin strings etc.
 
+- `sendAccepted`
+- `sendConflict`
+- `sendCreated`
 - `sendError` - 500
-- `sendPreflight` - Response to OPTIONS with CORS headers
-- `sendUnauthorized` - Unauthorized
+- `sendJSON_Encoded` - Standard Ok response with encoding
+- `sendNoContent`
+- `sendNotAcceptable`
+- `sendNotAllowed` - Method not supported / allowed
 - `sendNotFound` - 404
+- `sendNotModified`
+- `sendPreflight` - Response to OPTIONS with CORS headers
+- `sendTimeout`
 - `sendTooManyRequests` - Rate limit response (429)
-- `sendJSON_Encoded` - Standard Ok response with encoding
+- `sendTrace`
+- `sendUnauthorized` - Unauthorized
+- `sendUnprocessable`
+- `sendUnsupportedMediaType`
 - `sendSSE` - SSE header (leave the `stream` open)
 
 Responses allow for optional CORS headers as well as Server Timing meta data.
 
+## Response Object
+
+The response methods `sendXYZ` are also wrapped in a `Response` object which can make imports simpler and help organize code.
+
+```js
+import { Response } from '@johntalton/http-util/response/object'
+
+// ... sendNotFound becomes .notFound
+Response.notFound(stream, meta)
+```
+
 ## 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.
+Optional `byteLimit`, `contentLength` and `contentType` can be provided to hint the parser, as well as a `AbortSignal` to abandoned the reader.
+
+```js
+import { requestBody } from '@johntalton/http-util/body'
+
+const signal = // from someplace like a timeout for the overall request
+
+// limit time and size for the body
+// note: this does not consume the stream
+const futureBody = requestBody(stream, {
+  byteLimit: 1000 * 1000,
+  signal
+})
+
+// ... a few moments later ...
+
+// consume the stream
+const body = futureBody.json()
+
+```

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@johntalton/http-util",
-  "version": "2.0.0",
+  "version": "2.0.3",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./headers": "./src/index.js",
     "./body": "./src/body.js",
-    "./response": "./src/handle-stream-util.js"
+    "./response": "./src/response/index.js",
+    "./response/object": "./src/response/response.js"
   },
   "files": [
-    "src/*.js"
+    "src/*.js",
+    "src/response/*.js"
   ],
   "repository": {
     "url": "https://github.com/johntalton/http-util"

package/src/body.js

@@ -228,6 +228,9 @@ export async function bodyArrayBuffer(reader) {
  * @param {ReadableStream} reader
  */
 export async function bodyUint8Array(reader) {
+	// const blob = await bodyBlob(reader)
+	// return blob.bytes()
+
 	const buffer = await bodyArrayBuffer(reader)
 	return new Uint8Array(buffer)
 

package/src/conditional.js

@@ -0,0 +1,260 @@
+export const CONDITION_ETAG_SEPARATOR = ','
+export const CONDITION_ETAG_ANY = '*'
+export const CONDITION_ETAG_WEAK_PREFIX = 'W/'
+export const ETAG_QUOTE = '"'
+
+export const DATE_SPACE = ' '
+export const DATE_DAYS = [ 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun' ]
+export const DATE_MONTHS = [ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' ]
+export const DATE_SEPARATOR = ','
+export const DATE_TIME_SEPARATOR = ':'
+export const DATE_ZONE = 'GMT'
+
+/**
+ * @param {string} etag
+ */
+export function isValidEtag(etag) {
+	// %x21 / %x23-7E  and %x80-FF
+	for(const c of etag) {
+		if(c.charCodeAt(0) < 0x21) { return false }
+		if(c.charCodeAt(0) > 0xFF) { return false }
+		if(c === ETAG_QUOTE) { return false }
+	}
+	return true
+}
+
+/**
+ * @param {string} etag
+ */
+export function stripQuotes(etag) {
+	return etag.substring(1, etag.length - 1)
+}
+
+/**
+ * @param {string} etag
+ */
+export function isQuoted(etag) {
+	if(etag.length <= 2) { return false }
+	if(!etag.startsWith(ETAG_QUOTE)) { return false }
+	if(!etag.endsWith(ETAG_QUOTE)) { return false }
+	return true
+}
+
+/**
+ * @typedef {Object} EtagItem
+ * @property {boolean} weak
+ * @property {boolean} any
+ * @property {string} etag
+ */
+
+/**
+ * @typedef {Object} IMFFixDate
+ * @property {typeof DATE_DAYS[number]} dayName
+ * @property {number} day
+ * @property {typeof DATE_MONTHS[number]} month
+ * @property {number} year
+ * @property {number} hour
+ * @property {number} minute
+ * @property {number} second
+ * @property {Date} date
+ */
+
+export class Conditional {
+	/**
+	 * @param {string|undefined} matchHeader
+	 * @returns {Array<EtagItem>}
+	 */
+	static parseEtagList(matchHeader) {
+		if(matchHeader === undefined) { return [] }
+
+		return matchHeader.split(CONDITION_ETAG_SEPARATOR)
+			.map(etag => etag.trim())
+			.map(etag => {
+				if(etag.startsWith(CONDITION_ETAG_WEAK_PREFIX)) {
+					// weak
+					return {
+						weak: true,
+						etag: etag.substring(CONDITION_ETAG_WEAK_PREFIX.length)
+					}
+				}
+
+				// strong
+				return {
+					weak: false,
+					etag
+				}
+			})
+			.map(item => {
+				if(item.etag === CONDITION_ETAG_ANY) {
+					return {
+						...item,
+						any: true
+					}
+				}
+
+				// validated quoted
+				if(!isQuoted(item.etag)) { return undefined }
+				const etag = stripQuotes(item.etag)
+				if(!isValidEtag(etag)) { return undefined }
+				if(etag === CONDITION_ETAG_ANY) { return undefined }
+
+				return {
+					weak: item.weak,
+					any: false,
+					etag
+				}
+			})
+			.filter(item => item !== undefined)
+	}
+
+	/**
+	 * @param {String|string|undefined} matchHeader
+	 * @returns {IMFFixDate|undefined}
+	 */
+	static parseFixDate(matchHeader) {
+		if(matchHeader === undefined || matchHeader === null) { return undefined }
+		// if(!(typeof matchHeader === 'string') && (!(matchHeader instanceof String))) { return undefined }
+
+		// https://www.rfc-editor.org/rfc/rfc5322.html#section-3.3
+		// https://httpwg.org/specs/rfc9110.html#preferred.date.format
+		// <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT
+		// day-name "," SP date1 SP time-of-day SP GMT
+
+		if(matchHeader.length != 29) { return undefined }
+
+		//
+		const spaces = [
+			matchHeader.substring(4, 5),
+			matchHeader.substring(7, 8),
+			matchHeader.substring(11, 12),
+			matchHeader.substring(16, 17),
+			matchHeader.substring(25, 26)
+		]
+		const comma = matchHeader.substring(3, 4)
+		const timeSeparators = [
+			matchHeader.substring(19, 20),
+			matchHeader.substring(22, 23)
+		]
+		const gmt = matchHeader.substring(26)
+
+		//
+		if(comma !== DATE_SEPARATOR) { return undefined }
+		if(gmt !== DATE_ZONE) { return undefined }
+		for(const colon of timeSeparators) {
+			if(colon !== DATE_TIME_SEPARATOR) { return undefined }
+		}
+		for(const space of spaces) {
+			if(space !== DATE_SPACE) { return undefined }
+		}
+
+		//
+		const dayName = matchHeader.substring(0, 3)
+		const day = parseInt(matchHeader.substring(5, 7))
+		const month = matchHeader.substring(8, 11)
+		const year = parseInt(matchHeader.substring(12, 16))
+		const hour = parseInt(matchHeader.substring(17, 19))
+		const minute = parseInt(matchHeader.substring(20, 22))
+		const second = parseInt(matchHeader.substring(23, 25))
+
+		//
+		if(!DATE_DAYS.includes(dayName)) { return undefined }
+		if(!DATE_MONTHS.includes(month)) { return undefined }
+		if(!Number.isInteger(day)) { return undefined }
+		if(!Number.isInteger(year)) { return undefined }
+		if(!Number.isInteger(hour)) { return undefined }
+		if(!Number.isInteger(minute)) { return undefined }
+		if(!Number.isInteger(second)) { return undefined }
+
+		//
+		if(day > 31 || day <= 0) { return undefined }
+		if(year < 1900) { return undefined }
+		if(hour > 24 || hour < 0) { return undefined }
+		if(minute > 60 || minute < 0) { return undefined }
+		if(second > 60 || second < 0) { return undefined }
+
+		//
+		return {
+			dayName,
+			day,
+			month,
+			year,
+			hour,
+			minute,
+			second,
+			date: new Date(Date.UTC(year, DATE_MONTHS.indexOf(month), day, hour, minute, second)),
+			// temporal:
+		}
+	}
+}
+
+// Ok
+// console.log(Conditional.parseEtagList('"bfc13a64729c4290ef5b2c2730249c88ca92d82d"'))
+// console.log(Conditional.parseEtagList('W/"67ab43", "54ed21", "7892dd"'))
+// console.log(Conditional.parseEtagList('*'))
+// console.log(Conditional.parseEtagList('"!ÿ©"'))
+// console.log(Conditional.parseEtagList('"!","ÿ", "©"'))
+// console.log(Conditional.parseEtagList('"!","ÿ"   ,\t"©"'))
+
+// Error
+console.log(Conditional.parseEtagList('"*"'))
+// console.log(Conditional.parseEtagList('W/'))
+// console.log(Conditional.parseEtagList('W/"'))
+// console.log(Conditional.parseEtagList('W/""'))
+// console.log(Conditional.parseEtagList(''))
+// console.log(Conditional.parseEtagList('"'))
+// console.log(Conditional.parseEtagList('""'))
+// console.log(Conditional.parseEtagList('"""'))
+// console.log(Conditional.parseEtagList('" "'))
+// console.log(Conditional.parseEtagList('"\n"'))
+// console.log(Conditional.parseEtagList('"\t"'))
+
+//
+// const testsOk = [
+// 	'Sun, 06 Nov 1994 08:49:37 GMT',
+// 	'Sun, 06 Nov 1994 00:00:00 GMT',
+// 	'Tue, 01 Nov 1994 00:00:00 GMT',
+// 	'Thu, 06 Nov 3000 08:49:37 GMT',
+// 	'Sun, 06 Nov 1994 23:59:59 GMT',
+// 	new String('Sun, 06 Nov 1994 08:49:37 GMT'),
+// ]
+// for(const test of testsOk) {
+// 	const result = Conditional.parseFixDate(test)
+// 	if(result?.date.toUTCString() !== test.toString()) {
+// 		console.log('🛑', test, result, result?.date.toUTCString())
+// 		break
+// 	}
+// }
+
+// const testBad = [
+// 	undefined,
+// 	null,
+// 	{},
+// 	new String(),
+// 	'',
+// 	'Anything',
+// 	'   ,               :  :   GMT',
+// 	'Sun,    Nov        :  :   GMT',
+// 	'Sun, 00 Nov 0000 00:00:00 GMT',
+// 	'Sun, 06 Nov 1994 08-49-37 GMT',
+// 	'Sun  06 Nov 1994 08:49:37 GMT',
+// 	'FOO, 06 Nov 1994 08:49:37 GMT',
+// 	'Sun, 32 Nov 1994 08:49:37 GMT',
+// 	'Sun, 00 Nov 1994 08:49:37 GMT',
+// 	'Sun, 06 Nov 0900 08:49:37 GMT',
+// 	'Sun, 06 Nov 1994 08:49:37 UTC',
+// 	'Sun, 06 Nov 1994 30:49:37 GMT',
+// 	'Sun,\t06 Nov 1994 08:49:37 GMT',
+
+// 	'Sunday, 06-Nov-94 08:49:37 GMT',
+// 	'Sun Nov  6 08:49:37 1994',
+// 	'Sun Nov  6 08:49:37 1994      ',
+
+// ]
+// for(const test of testBad) {
+// 	const result = Conditional.parseFixDate(test)
+// 	if(result !== undefined) {
+// 		console.log('🛑', test, result)
+// 		break
+// 	}
+// }
+

package/src/index.js

@@ -2,9 +2,10 @@ export * from './accept-encoding.js'
 export * from './accept-language.js'
 export * from './accept-util.js'
 export * from './accept.js'
+export * from './conditional.js'
 export * from './content-disposition.js'
 export * from './content-type.js'
 export * from './forwarded.js'
 export * from './multipart.js'
 export * from './rate-limit.js'
-export * from './server-timing.js'
+export * from './server-timing.js'

package/src/response/accepted.js

@@ -0,0 +1,39 @@
+import http2 from 'node:http2'
+import { CONTENT_TYPE_JSON } from '../content-type.js'
+import {
+	HTTP_HEADER_TIMING_ALLOW_ORIGIN,
+	HTTP_HEADER_SERVER_TIMING,
+	ServerTiming
+} from '../server-timing.js'
+
+/** @import { ServerHttp2Stream } from 'node:http2' */
+/** @import { Metadata } from './defs.js' */
+
+const {
+  HTTP_STATUS_ACCEPTED
+} = http2.constants
+
+const {
+  HTTP2_HEADER_STATUS,
+  HTTP2_HEADER_SERVER,
+  HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN
+} = http2.constants
+
+/**
+ * @param {ServerHttp2Stream} stream
+ * @param {Metadata} meta
+ */
+export function sendAccepted(stream, meta) {
+	stream.respond({
+		[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN]: meta.origin,
+		[HTTP2_HEADER_STATUS]: HTTP_STATUS_ACCEPTED,
+		// [HTTP2_HEADER_CONTENT_TYPE]: CONTENT_TYPE_JSON,
+		[HTTP2_HEADER_SERVER]: meta.servername,
+		[HTTP_HEADER_TIMING_ALLOW_ORIGIN]: meta.origin,
+		[HTTP_HEADER_SERVER_TIMING]: ServerTiming.encode(meta.performance)
+	})
+
+	// stream.write(JSON.stringify( ... ))
+
+	stream.end()
+}

package/src/response/conflict.js

@@ -0,0 +1,39 @@
+import http2 from 'node:http2'
+import { CONTENT_TYPE_JSON } from '../content-type.js'
+import {
+	HTTP_HEADER_TIMING_ALLOW_ORIGIN,
+	HTTP_HEADER_SERVER_TIMING,
+	ServerTiming
+} from '../server-timing.js'
+
+/** @import { ServerHttp2Stream } from 'node:http2' */
+/** @import { Metadata } from './defs.js' */
+
+const {
+	HTTP_STATUS_CONFLICT
+} = http2.constants
+
+const {
+	HTTP2_HEADER_STATUS,
+	HTTP2_HEADER_SERVER,
+	HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN
+} = http2.constants
+
+/**
+ * @param {ServerHttp2Stream} stream
+ * @param {Metadata} meta
+ */
+export function sendConflict(stream, meta) {
+	stream.respond({
+		[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN]: meta.origin,
+		[HTTP2_HEADER_STATUS]: HTTP_STATUS_CONFLICT,
+		// [HTTP2_HEADER_CONTENT_TYPE]: CONTENT_TYPE_JSON,
+		[HTTP2_HEADER_SERVER]: meta.servername,
+		[HTTP_HEADER_TIMING_ALLOW_ORIGIN]: meta.origin,
+		[HTTP_HEADER_SERVER_TIMING]: ServerTiming.encode(meta.performance)
+	})
+
+	// stream.write(JSON.stringify( ... ))
+
+	stream.end()
+}

package/src/response/created.js

@@ -0,0 +1,42 @@
+import http2 from 'node:http2'
+import { CONTENT_TYPE_JSON } from '../content-type.js'
+import {
+	HTTP_HEADER_TIMING_ALLOW_ORIGIN,
+	HTTP_HEADER_SERVER_TIMING,
+	ServerTiming
+} from '../server-timing.js'
+
+/** @import { ServerHttp2Stream } from 'node:http2' */
+/** @import { Metadata } from './defs.js' */
+
+const {
+	HTTP_STATUS_CREATED
+} = http2.constants
+
+const {
+	HTTP2_HEADER_STATUS,
+	HTTP2_HEADER_SERVER,
+	HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN,
+	HTTP2_HEADER_LOCATION
+} = http2.constants
+
+/**
+ * @param {ServerHttp2Stream} stream
+ * @param {URL} location
+ * @param {Metadata} meta
+ */
+export function sendCreated(stream, location, meta) {
+	stream.respond({
+		[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN]: meta.origin,
+		[HTTP2_HEADER_STATUS]: HTTP_STATUS_CREATED,
+		// [HTTP2_HEADER_CONTENT_TYPE]: CONTENT_TYPE_JSON,
+		[HTTP2_HEADER_SERVER]: meta.servername,
+		[HTTP2_HEADER_LOCATION]: location.href,
+		[HTTP_HEADER_TIMING_ALLOW_ORIGIN]: meta.origin,
+		[HTTP_HEADER_SERVER_TIMING]: ServerTiming.encode(meta.performance),
+	})
+
+	// stream.write(JSON.stringify( ... ))
+
+	stream.end()
+}

package/src/response/defs.js

@@ -0,0 +1,34 @@
+
+export const HTTP_HEADER_ORIGIN = 'origin'
+export const HTTP_HEADER_USER_AGENT = 'user-agent'
+export const HTTP_HEADER_FORWARDED = 'forwarded'
+export const HTTP_HEADER_SEC_CH_UA = 'sec-ch-ua'
+export const HTTP_HEADER_SEC_CH_PLATFORM = 'sec-ch-ua-platform'
+export const HTTP_HEADER_SEC_CH_MOBILE = 'sec-ch-ua-mobile'
+export const HTTP_HEADER_SEC_FETCH_SITE = 'sec-fetch-site'
+export const HTTP_HEADER_SEC_FETCH_MODE = 'sec-fetch-mode'
+export const HTTP_HEADER_SEC_FETCH_DEST = 'sec-fetch-dest'
+export const HTTP_HEADER_ACCEPT_POST = 'accept-post'
+
+export const DEFAULT_METHODS = [ 'HEAD', 'GET', 'POST', 'PATCH', 'DELETE' ]
+
+export const HTTP2_HEADER_ACCESS_CONTROL_MAX_AGE = 'access-control-max-age'
+export const PREFLIGHT_AGE_SECONDS = '500'
+
+
+/** @import { TimingsInfo } from '../server-timing.js' */
+
+/**
+ * @typedef {Object} Metadata
+ * @property {Array<TimingsInfo>} performance
+ * @property {string|undefined} servername
+ * @property {string|undefined} origin
+ * @property {string|undefined} [etag]
+ */
+
+/**
+ * @typedef {Object} SSEOptions
+ * @property {boolean} [active]
+ * @property {boolean} [bom]
+ */
+

package/src/response/error.js

@@ -0,0 +1,47 @@
+import http2 from 'node:http2'
+import {
+	CONTENT_TYPE_TEXT
+} from '../content-type.js'
+
+const {
+	HTTP2_HEADER_STATUS,
+	HTTP2_HEADER_CONTENT_TYPE,
+	HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN,
+	HTTP2_HEADER_SERVER
+} = http2.constants
+
+const {
+	HTTP_STATUS_INTERNAL_SERVER_ERROR
+} = http2.constants
+
+/** @import { ServerHttp2Stream } from 'node:http2' */
+/** @import { Metadata } from './defs.js' */
+
+/**
+ * @param {ServerHttp2Stream} stream
+ * @param {string} message
+ * @param {Metadata} meta
+ */
+export function sendError(stream, message, meta) {
+	console.error('500', message)
+
+	if(stream === undefined) { return }
+	if(stream.closed) { return }
+
+	if(!stream.headersSent) {
+		stream.respond({
+			[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN]: meta.origin,
+			[HTTP2_HEADER_STATUS]: HTTP_STATUS_INTERNAL_SERVER_ERROR,
+			[HTTP2_HEADER_CONTENT_TYPE]: CONTENT_TYPE_TEXT,
+			[HTTP2_HEADER_SERVER]: meta.servername
+		})
+	}
+
+	// protect against HEAD calls
+	if(stream.writable) {
+		if(message !== undefined) { stream.write(message) }
+	}
+
+	stream.end()
+	if(!stream.closed) { stream.close() }
+}

package/src/response/index.js

@@ -0,0 +1,20 @@
+export * from './defs.js'
+
+export * from './accepted.js'
+export * from './conflict.js'
+export * from './created.js'
+export * from './error.js'
+export * from './json.js'
+export * from './no-content.js'
+export * from './not-acceptable.js'
+export * from './not-allowed.js'
+export * from './not-found.js'
+export * from './not-modified.js'
+export * from './preflight.js'
+export * from './sse.js'
+export * from './timeout.js'
+export * from './too-many-requests.js'
+export * from './trace.js'
+export * from './unauthorized.js'
+export * from './unsupported-media.js'
+export * from './unprocessable.js'