@johntalton/http-util 4.1.0 → 5.0.0

package/README.md

@@ -2,9 +2,9 @@
 
 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](#header-parsers)
+- [Stream Response methods](#response)
+- [Body parser](#body)
 
 ## Header Parsers
 ### From Client:
@@ -44,24 +44,37 @@ const bestMatchingType = Accept.select(acceptHeader, supportedType)
 
 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
-- `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)
-- `sendTrace`
-- `sendUnauthorized` - Unauthorized
-- `sendUnprocessable`
-- `sendUnsupportedMediaType`
-- `sendSSE` - SSE header (leave the `stream` open)
+- [`sendAccepted`](#responseaccepted)
+- [`sendConflict`](#responseconflict)
+- [`sendContentTooLarge`](#)
+- [`sendCreated`](#responsecreated)
+- [`sendError`](#responseerror) - 500
+- [`sendGone`](#)
+- [`sendImATeapot`](#)
+- [`sendInsufficientStorage`](#)
+- [`sendJSON_Encoded`](#responsejson) - Standard Ok response with encoding
+- [`sendMovedPermanently`](#)
+- [`sendMultipleChoices`](#)
+- [`sendNoContent`](#responsenocontent)
+- [`sendNotAcceptable`](#responsenotacceptable)
+- [`sendNotAllowed`](#responsenotallowed) - Method not supported / allowed
+- [`sendNotFound`](#responsenotfound) - 404
+- [`sendNotImplemented`](#responsenotimplemented)
+- [`sendNotModified`](#responsenotmodified)
+- [`sendPartialContent`](#)
+- [`sendPreconditionFailed`](#responsepreconditionfailed)
+- [`sendPreflight`](#responsepreflight) - Response to OPTIONS with CORS headers
+- [`sendRangeNotSatisfiable`](#)
+- [`sendSeeOther`](#)
+- [`sendTemporaryRedirect`](#)
+- [`sendTimeout`](#responsetimeout)
+- [`sendTooManyRequests`](#responsetoomanyrequests) - Rate limit response (429)
+- [`sendTrace`](#responsetrace)
+- [`sendUnauthorized`](#responseunauthorized) - Unauthorized
+- [`sendUnavailable`](#responseunavailable)
+- [`sendUnprocessable`](#responseunprocessable)
+- [`sendUnsupportedMediaType`](#responseunsupportedmediatype)
+- [`sendSSE`](#responsesse) - SSE header (leave the `stream` open)
 
 Responses allow for optional CORS headers as well as Server Timing meta data.
 
@@ -102,3 +115,201 @@ const futureBody = requestBody(stream, {
 const body = futureBody.json()
 
 ```
+
+## Response method API
+
+All response methods take in the `stream` and a `meta` property.
+
+Additional parameters are specific to each return type.
+
+Each return type semantic may also expose header (in addition to the standard headers) to the calling code as needed.
+
+Some common objects can be passed such as `EtagItem`, `CacheControlOptions` and `Metadata` have their own structure.
+
+Many parameters accept `undefined` to skip/ignore the usage
+
+### Response.accepted
+
+Parameters:
+- stream
+- meta
+
+### Response.conflict
+
+Parameters:
+- stream
+- meta
+
+
+### Response.created
+
+Parameters:
+- stream
+- location
+- etag
+- meta
+
+Additional Exposed Headers:
+- location
+
+### Response.error
+
+Parameters:
+- stream
+- meta
+
+
+### Response.json
+
+Parameters:
+- stream
+- object
+- encoding - undefined | 'identity' | 'br' | 'gzip' | 'deflate' | 'zstd'
+- etag
+- age
+- cacheControl
+- supportedQueryTypes - undefined | Array of supported query types
+- meta
+
+Additional Exposed Headers
+- age
+- accept-query
+
+### Response.noContent
+
+Parameters:
+- stream
+- etag
+- meta
+
+### Response.notAcceptable
+
+Parameters:
+- stream
+- supportedTypes
+- meta
+
+### Response.notAllowed
+
+Parameters:
+- stream
+- methods - Array of allowed methods
+- meta
+
+Additional Exposed Headers:
+- allow
+
+### Response.notFound
+
+Parameters:
+- stream
+- message
+- meta
+
+### Response.notImplemented
+
+Parameters:
+- stream
+- message
+- meta
+
+### Response.notModified
+
+Parameters:
+- stream
+- etag
+- age
+- cacheControl
+- meta
+
+Additional Exposed Headers:
+- age
+
+### Response.preconditionFailed
+
+Parameters:
+- stream
+- meta
+
+### Response.preflight
+
+Parameters:
+- stream
+- methods
+- supportedQueryTypes - undefined | Array of supported types
+- meta
+
+Additional Exposed Headers:
+- accept-query
+
+### Response.sse
+
+Parameters:
+- stream
+- meta
+
+
+### Response.timeout
+
+Parameters:
+- stream
+- meta
+
+
+### Response.tooManyRequests
+
+Parameters:
+- stream
+- limitInfo - `RateLimitInfo`
+- policies - Array of `RateLimitPolicyInfo`
+- meta
+
+Additional Exposed Headers:
+- retry-after
+- rate-limit
+- rate-limit-policy
+
+### Response.trace
+
+Parameters:
+- stream
+- method
+- url
+- headers
+- meta
+
+### Response.unauthorized
+
+Parameters:
+- stream
+- meta
+
+
+### Response.unavailable
+
+Parameters:
+- stream
+- message
+- retryAfter
+- meta
+
+Additional Exposed Headers:
+- retry-after
+
+### Response.unprocessable
+
+Parameters:
+- stream
+- meta
+
+### Response.unsupportedMediaType
+
+Parameters:
+- stream
+- acceptableMediaTypes
+- supportedQueryTypes
+- meta
+
+Additional Exposed Headers:
+- accept-query
+- accept-post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johntalton/http-util",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/body.js

@@ -1,15 +1,14 @@
-import { CHARSET_UTF8, MIME_TYPE_MULTIPART_FORM_DATA, MIME_TYPE_URL_FORM_DATA } from './content-type.js'
+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'
- */
+/** @import { Readable } from 'node:stream' */
+/** @import { ContentType } from './content-type.js' */
 
 /**
  * @typedef {Object} BodyOptions
@@ -32,7 +31,6 @@ export const DEFAULT_BYTE_LIMIT = 1024 * 1024 //
  * @property { () => Promise<any> } json
  */
 
-
 /**
  * @param {Readable} stream
  * @param {BodyOptions} [options]
@@ -92,9 +90,9 @@ export function requestBody(stream, options) {
 				// return
 			}
 
-
 			const listener = () => {
-				controller.error(new Error('Abort Signal Timed out'))
+				stats.closed = true
+				controller.error(new Error('Abort Signal'))
 			}
 
 			signal?.addEventListener('abort', listener, { once: true })
@@ -146,6 +144,8 @@ export function requestBody(stream, options) {
 
 			stream.on('close', () => {
 				// console.log('body reader stream close')
+				signal?.removeEventListener('abort', listener)
+
 				if(!stats.closed) {
 					stats.closed = true
 					controller.close()

package/src/cache-control.js

@@ -12,10 +12,12 @@
 
 export class CacheControl {
 	/**
-	 * @param {CacheControlOptions} options
+	 * @param {CacheControlOptions|undefined} options
 	 * @returns {string|undefined}
 	 */
 	static encode(options) {
+		if(options === undefined) { return undefined }
+
 		const {
 			pub,
 			priv,
@@ -46,6 +48,9 @@ export class CacheControl {
 			result.push(`stale-if-error=${staleIfError}`)
 		}
 
+		//
+		if(result.length === 0) { return undefined }
+
 		return result.join(', ')
 	}
 }

package/src/conditional.js

@@ -102,6 +102,31 @@ export class ETag {
 	 * @returns {AnyEtagItem}
 	 */
 	static any() { return ANY_ETAG_ITEM }
+
+	/**
+	 * @param {string|undefined} raw
+	 * @returns {EtagItem|undefined}
+	 */
+	static parse(raw) {
+		if(raw === undefined) { return undefined }
+
+		const rawEtag = raw.trim()
+		const weak = rawEtag.startsWith(CONDITION_ETAG_WEAK_PREFIX)
+		const quotedEtag = weak ? rawEtag.substring(CONDITION_ETAG_WEAK_PREFIX.length) : rawEtag
+
+		if(quotedEtag === CONDITION_ETAG_ANY) { return ANY_ETAG_ITEM }
+
+		if(!isQuoted(quotedEtag)) { return undefined }
+		const etag = stripQuotes(quotedEtag)
+		if(!isValidEtag(etag)) { return undefined }
+		if(etag === CONDITION_ETAG_ANY) { return undefined }
+
+		return {
+			weak,
+			any: false,
+			etag
+		}
+	}
 }
 
 export class Conditional {
@@ -131,40 +156,7 @@ export class Conditional {
 		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 ANY_ETAG_ITEM }
-
-				// 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 }
-
-				/** @type {WeakEtagItem | NotWeakEtagItem} */
-				const result = {
-					weak: item.weak,
-					any: false,
-					etag
-				}
-
-				return result
-			})
+			.map(ETag.parse)
 			.filter(item => item !== undefined)
 	}
 

package/src/content-range.js

@@ -0,0 +1,59 @@
+import { RANGE_UNITS_BYTES } from "./response/defs.js"
+
+export const CONTENT_RANGE_UNKNOWN = '*'
+export const CONTENT_RANGE_SEPARATOR = '-'
+export const CONTENT_RANGE_SIZE_SEPARATOR = '/'
+
+export const DEFAULT_CONTENT_RANGE_DIRECTIVE = {
+	units: RANGE_UNITS_BYTES,
+	range: CONTENT_RANGE_UNKNOWN,
+	size: CONTENT_RANGE_UNKNOWN
+}
+/**
+ * @typedef {Object} ContentRangeDirective
+ * @property {RANGE_UNITS_BYTES|undefined} [units]
+ * @property {{ start: number, end: number }|CONTENT_RANGE_UNKNOWN|undefined} [range]
+ * @property {number|CONTENT_RANGE_UNKNOWN|undefined} [size]
+ */
+
+export class ContentRange {
+	/**
+	 * @param {ContentRangeDirective|undefined} rangeDirective
+	 * @returns {string|undefined}
+	 */
+	static encode(rangeDirective) {
+		if(rangeDirective === undefined) { return undefined }
+
+		const units = rangeDirective.units ?? DEFAULT_CONTENT_RANGE_DIRECTIVE.units
+		const size = rangeDirective.size ?? DEFAULT_CONTENT_RANGE_DIRECTIVE.size
+		const range = rangeDirective.range ?? DEFAULT_CONTENT_RANGE_DIRECTIVE.range
+
+		if(units !== RANGE_UNITS_BYTES) { return undefined }
+		if(size !== CONTENT_RANGE_UNKNOWN && !Number.isInteger(size)) { return undefined }
+
+		if((typeof range === 'string')) {
+			if(range !== CONTENT_RANGE_UNKNOWN) { return undefined }
+			return `${units} ${CONTENT_RANGE_UNKNOWN}${CONTENT_RANGE_SIZE_SEPARATOR}${size}`
+		}
+
+		const rangeStr = `${range.start}${CONTENT_RANGE_SEPARATOR}${range.end}`
+		return `${units} ${rangeStr}${CONTENT_RANGE_SIZE_SEPARATOR}${size}`
+	}
+}
+
+// console.log(ContentRange.encode({}))
+// console.log(ContentRange.encode({ size: '*' }))
+// console.log(ContentRange.encode({ units: 'bytes' }))
+// console.log(ContentRange.encode({ range: '*' }))
+// console.log(ContentRange.encode({ range: '*', size: '*' }))
+
+// console.log()
+// console.log(ContentRange.encode({ range: { start: 0, end: 1024 } }))
+// console.log(ContentRange.encode({ range: { start: 0, end: 1024 }, size: 1024  }))
+// console.log(ContentRange.encode({ range: '*', size: 1024 }))
+// console.log(ContentRange.encode({ size: 1024 }))
+
+// console.log()
+// console.log(ContentRange.encode({ units: 'bob' }))
+// console.log(ContentRange.encode({ range: 'bob' }))
+// console.log(ContentRange.encode({ size: 'bob' }))

package/src/content-type.js

@@ -5,9 +5,11 @@ export const MIME_TYPE_EVENT_STREAM = 'text/event-stream'
 export const MIME_TYPE_XML = 'application/xml'
 export const MIME_TYPE_URL_FORM_DATA = 'application/x-www-form-urlencoded'
 export const MIME_TYPE_MULTIPART_FORM_DATA = 'multipart/form-data'
+export const MIME_TYPE_MULTIPART_RANGE = 'multipart/byteranges'
 export const MIME_TYPE_OCTET_STREAM = 'application/octet-stream'
 export const MIME_TYPE_MESSAGE_HTTP = 'message/http'
 
+
 export const KNOWN_CONTENT_TYPES = [
 	'application', 'audio', 'image', 'message',
 	'multipart','text', 'video'

package/src/index.js

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

package/src/multipart.js

@@ -1,5 +1,17 @@
+import { ReadableStream } from 'node:stream/web'
+
 import { parseContentDisposition } from './content-disposition.js'
 import { parseContentType } from './content-type.js'
+import { ContentRange } from './content-range.js'
+
+/** @import { ContentRangeDirective } from './content-range.js' */
+/** @import { SendBody } from './response/send-util.js' */
+
+/**
+ * @typedef {Object} MultipartBytePart
+ * @property {SendBody} obj
+ * @property {ContentRangeDirective} range
+ */
 
 export const DISPOSITION_FORM_DATA = 'form-data'
 
@@ -12,7 +24,8 @@ export const EMPTY = ''
 
 export const MULTIPART_HEADER = {
 	CONTENT_DISPOSITION: 'content-disposition',
-	CONTENT_TYPE: 'content-type'
+	CONTENT_TYPE: 'content-type',
+	CONTENT_RANGE: 'content-range'
 }
 
 export const MULTIPART_STATE = {
@@ -29,6 +42,15 @@ export class Multipart {
 	 * @param {string} [charset='utf8']
 	 */
 	static parse(text, boundary, charset = 'utf8') {
+		return Multipart.parse_FormData(text, boundary, charset)
+	}
+
+	/**
+	 * @param {string} text
+	 * @param {string} boundary
+	 * @param {string} [charset='utf8']
+	 */
+	static parse_FormData(text, boundary, charset = 'utf8') {
 		// console.log({ boundary, text })
 		const formData = new FormData()
 
@@ -114,36 +136,62 @@ export class Multipart {
 
 		return formData
 	}
-}
 
+	/**
+	 * @param {string} contentType
+	 * @param {Array<MultipartBytePart>} parts
+	 * @param {number|undefined} contentLength
+	 * @param {string} boundary
+	 * @returns {ReadableStream<Uint8Array>}
+	 */
+	static encode_Bytes(contentType, parts, contentLength, boundary) {
+		const boundaryBegin = `${BOUNDARY_MARK}${boundary}`
+		const boundaryEnd = `${BOUNDARY_MARK}${boundary}${BOUNDARY_MARK}`
+
+		return new ReadableStream({
+			type: 'bytes',
+			async start(controller) {
+				const encoder = new TextEncoder()
+
+				for (const part of parts) {
+					controller.enqueue(encoder.encode(`${boundaryBegin}${MULTIPART_SEPARATOR}`))
+					controller.enqueue(encoder.encode(`${MULTIPART_HEADER.CONTENT_TYPE}: ${contentType}${MULTIPART_SEPARATOR}`))
+					controller.enqueue(encoder.encode(`${MULTIPART_HEADER.CONTENT_RANGE}: ${ContentRange.encode({ ...part.range, size: contentLength })}${MULTIPART_SEPARATOR}`))
+					controller.enqueue(encoder.encode(MULTIPART_SEPARATOR))
+					// controller.enqueue(encoder.encode(MULTIPART_SEPARATOR))
+
+					if(part.obj instanceof ReadableStream) {
+						for await (const chunk of part.obj) {
+							if(chunk instanceof ArrayBuffer || ArrayBuffer.isView(chunk)) {
+								controller.enqueue(chunk)
+							}
+							else if(typeof chunk === 'string'){
+								controller.enqueue(encoder.encode(chunk))
+							}
+							else {
+								// console.log('chunk type', typeof chunk)
+								controller.enqueue(Uint8Array.from([ chunk ]))
+							}
+						}
+					}
+					else if(part.obj instanceof ArrayBuffer || ArrayBuffer.isView(part.obj)) {
+						controller.enqueue(part.obj)
+					}
+					else if(typeof part.obj === 'string'){
+						controller.enqueue(encoder.encode(part.obj))
+					}
+					else {
+						// console.log('error', typeof part.obj, part.obj)
+						throw new Error('unknown part type')
+					}
+
+					controller.enqueue(encoder.encode(MULTIPART_SEPARATOR))
+				}
 
+				controller.enqueue(encoder.encode(boundaryEnd))
 
-// const test = '--X-INSOMNIA-BOUNDARY\r\n' +
-//     'Content-Disposition: form-data; name="u"\r\n' +
-//     '\r\n' +
-//     'alice\r\n' +
-//     '--X-INSOMNIA-BOUNDARY\r\n' +
-//     'Content-Disposition: form-data; name="user"\r\n' +
-//     '\r\n' +
-//     'jeff\r\n' +
-//     '--X-INSOMNIA-BOUNDARY--\r\n'
-// const result = Multipart.parse(test, 'X-INSOMNIA-BOUNDARY')
-// console.log(result)
-
-
-// const test = [
-// 	'-----------------------------paZqsnEHRufoShdX6fh0lUhXBP4k',
-//  'Content-Disposition: form-data; '
-//    + 'name="upload_file_0"; filename="テスト.dat"',
-//  'Content-Type: application/octet-stream',
-//  '',
-//  'A'.repeat(1023),
-//  '-----------------------------paZqsnEHRufoShdX6fh0lUhXBP4k--'
-// ].join('\r\n')
-// const result = Multipart.parse(test, '---------------------------paZqsnEHRufoShdX6fh0lUhXBP4k')
-// console.log(result)
-
-
-// const test = '--X-INSOMNIA-BOUNDARY--\r\n'
-// const result = Multipart.parse(test, 'X-INSOMNIA-BOUNDARY')
-// console.log(result)
+      	controller.close()
+			}
+		})
+	}
+}