@johntalton/http-util 3.0.0 → 4.0.0

package/package.json

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

package/src/body.js

@@ -13,7 +13,7 @@ export const DEFAULT_BYTE_LIMIT = 1024 * 1024 //
 
 /**
  * @typedef {Object} BodyOptions
- * @property {AbortSignal} [signal]
+ * @property {AbortSignal|undefined} [signal]
  * @property {number} [byteLimit]
  * @property {number} [contentLength]
  * @property {ContentType|undefined} [contentType]

package/src/cache-control.js

@@ -0,0 +1,57 @@
+/** @typedef {'no-cache'|'no-store'|'no-transform'|'must-revalidate'|'immutable'|'must-understand'} Directives */
+
+/**
+ * @typedef {Object} CacheControlOptions
+ * @property {boolean|undefined} [priv]
+ * @property {boolean|undefined} [pub]
+ * @property {number|undefined} [maxAge]
+ * @property {number|undefined} [staleWhileRevalidate]
+ * @property {number|undefined} [staleIfError]
+ * @property {Directives|Array<Directives>|undefined} [directives]
+ */
+
+export class CacheControl {
+	/**
+	 * @param {CacheControlOptions} options
+	 * @returns {string|undefined}
+	 */
+	static encode(options) {
+		const {
+			pub,
+			priv,
+			maxAge,
+			directives,
+			staleWhileRevalidate,
+			staleIfError
+		} = options
+
+		const result = []
+
+		if(pub !== undefined && pub && !priv) { result.push('public') }
+		if(priv !== undefined && priv && !pub) { result.push('private') }
+
+		if(directives !== undefined) {
+			result.push(...(Array.isArray(directives) ? directives : [ directives ]))
+		}
+
+		if(maxAge !== undefined && Number.isInteger(maxAge) && maxAge >= 0) {
+			result.push(`max-age=${maxAge}`)
+		}
+
+		if(staleWhileRevalidate !== undefined && Number.isInteger(staleWhileRevalidate) && staleWhileRevalidate >= 0) {
+			result.push(`stale-while-revalidate=${staleWhileRevalidate}`)
+		}
+
+		if(staleIfError !== undefined && Number.isInteger(staleIfError) && staleIfError >= 0) {
+			result.push(`stale-if-error=${staleIfError}`)
+		}
+
+		return result.join(', ')
+	}
+}
+
+// console.log(CacheControl.encode({
+// 	priv: true,
+// 	maxAge: 60,
+// 	directives: ['must-revalidate', 'no-transform']
+// }))

package/src/conditional.js

@@ -31,7 +31,7 @@
  * @property {number} hour
  * @property {number} minute
  * @property {number} second
- * @property {Date} date
+ * @property {Date|undefined} [date]
  */
 
 export const CONDITION_ETAG_SEPARATOR = ','
@@ -79,6 +79,31 @@ export function isQuoted(etag) {
 	return true
 }
 
+export class ETag {
+	/**
+	 * @param {string} etag
+	 * @returns {WeakEtagItem}
+	 */
+	static weak(etag) {
+		if(!isValidEtag(etag)) { throw new Error('invalid etag format') }
+		return { any: false, weak: true, etag }
+	}
+
+	/**
+	 * @param {string} etag
+	 * @returns {NotWeakEtagItem}
+	 */
+	static strong(etag) {
+		if(!isValidEtag(etag)) { throw new Error('invalid etag format') }
+		return { any: false, weak: false, etag }
+	}
+
+	/**
+	 * @returns {AnyEtagItem}
+	 */
+	static any() { return ANY_ETAG_ITEM }
+}
+
 export class Conditional {
 	/**
 	 * @param {EtagItem|undefined} etagItem
@@ -143,6 +168,34 @@ export class Conditional {
 			.filter(item => item !== undefined)
 	}
 
+	/**
+	 * @param {Array<EtagItem>} etagItemList
+	 */
+	static hasAny(etagItemList) {
+		return etagItemList.find(item => item.any) !== undefined
+	}
+
+	/**
+	 * @param {Array<EtagItem>} etagItemList
+	 * @param {string} etag
+	 */
+	static hasEtag(etagItemList, etag) {
+		return etagItemList.find(item => item.etag === etag) !== undefined
+	}
+
+	/**
+	 * @param {IMFFixDate|undefined} fixDate
+	 * @returns {string|undefined}
+	 */
+	static encodeFixDate(fixDate) {
+		if(fixDate === undefined) { return undefined }
+		if(fixDate.date !== undefined) { return fixDate.date.toUTCString() }
+
+		const { year, month, day, hour, minute, second } = fixDate
+		const d = new Date(Date.UTC(year, DATE_MONTHS.indexOf(month), day, hour, minute, second))
+		return d.toUTCString()
+	}
+
 	/**
 	 * @param {String|string|undefined} matchHeader
 	 * @returns {IMFFixDate|undefined}

package/src/response/header-util.js

@@ -24,6 +24,8 @@ const {
 export function coreHeaders(status, contentType, meta) {
 	return {
 		[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN]: meta.origin,
+		// Access-Control-Expose-Headers
+		// Access-Control-Allow-Credentials // for non-preflight
 		[HTTP2_HEADER_STATUS]: status,
 		[HTTP2_HEADER_CONTENT_TYPE]: contentType,
 		[HTTP2_HEADER_SERVER]: meta.servername

package/src/response/json.js

@@ -11,10 +11,12 @@ import {
 } from '../content-type.js'
 import { send } from './send-util.js'
 import { Conditional } from '../conditional.js'
+import { CacheControl } from '../cache-control.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
 /** @import { EtagItem } from '../conditional.js' */
+/** @import { CacheControlOptions } from '../cache-control.js' */
 
 /** @typedef { (data: string, charset: BufferEncoding) => Buffer } EncoderFun */
 
@@ -22,7 +24,8 @@ const {
   HTTP2_HEADER_CONTENT_ENCODING,
   HTTP2_HEADER_VARY,
   HTTP2_HEADER_CACHE_CONTROL,
-  HTTP2_HEADER_ETAG
+  HTTP2_HEADER_ETAG,
+	HTTP2_HEADER_AGE
 } = http2.constants
 
 const { HTTP_STATUS_OK } = http2.constants
@@ -40,9 +43,11 @@ export const ENCODER_MAP = new Map([
  * @param {Object} obj
  * @param {string|undefined} encoding
  * @param {EtagItem|undefined} etag
+ * @param {number|undefined} age
+ * @param {CacheControlOptions} cacheControl
  * @param {Metadata} meta
  */
-export function sendJSON_Encoded(stream, obj, encoding, etag, meta) {
+export function sendJSON_Encoded(stream, obj, encoding, etag, age, cacheControl, meta) {
 	if(stream.closed) { return }
 
 	const json = JSON.stringify(obj)
@@ -63,8 +68,8 @@ export function sendJSON_Encoded(stream, obj, encoding, etag, meta) {
 	send(stream, HTTP_STATUS_OK, {
 			[HTTP2_HEADER_CONTENT_ENCODING]: actualEncoding,
 			[HTTP2_HEADER_VARY]: 'Accept, Accept-Encoding',
-			[HTTP2_HEADER_CACHE_CONTROL]: 'private',
-			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag)
-			// [HTTP2_HEADER_AGE]: age
+			[HTTP2_HEADER_CACHE_CONTROL]: CacheControl.encode(cacheControl),
+			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag),
+			[HTTP2_HEADER_AGE]: age !== undefined ? `${age}` : undefined
 		}, CONTENT_TYPE_JSON, encodedData, meta)
 }

package/src/response/not-modified.js

@@ -1,10 +1,12 @@
 import http2 from 'node:http2'
 import { send } from './send-util.js'
 import { Conditional } from '../conditional.js'
+import { CacheControl } from '../cache-control.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
 /** @import { EtagItem } from '../conditional.js' */
+/** @import { CacheControlOptions } from '../cache-control.js' */
 
 const {
 	HTTP2_HEADER_AGE,
@@ -19,12 +21,13 @@ const { HTTP_STATUS_NOT_MODIFIED } = http2.constants
  * @param {ServerHttp2Stream} stream
  * @param {EtagItem|undefined} etag
  * @param {number|undefined} age
+ * @param {CacheControlOptions} cacheControl
  * @param {Metadata} meta
  */
-export function sendNotModified(stream, etag, age, meta) {
+export function sendNotModified(stream, etag, age, cacheControl, meta) {
 	send(stream, HTTP_STATUS_NOT_MODIFIED, {
 			[HTTP2_HEADER_VARY]: 'Accept, Accept-Encoding',
-			[HTTP2_HEADER_CACHE_CONTROL]: 'private',
+			[HTTP2_HEADER_CACHE_CONTROL]: CacheControl.encode(cacheControl),
 			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag),
 			[HTTP2_HEADER_AGE]: age !== undefined ? `${age}` : undefined
 		}, undefined, undefined, meta)

package/src/response/preflight.js

@@ -11,7 +11,10 @@ import { send } from './send-util.js'
 const {
 	HTTP2_HEADER_CONTENT_TYPE,
 	HTTP2_HEADER_ACCESS_CONTROL_ALLOW_METHODS,
-	HTTP2_HEADER_ACCESS_CONTROL_ALLOW_HEADERS
+	HTTP2_HEADER_ACCESS_CONTROL_ALLOW_HEADERS,
+	HTTP2_HEADER_IF_MATCH,
+	HTTP2_HEADER_IF_NONE_MATCH,
+	HTTP2_HEADER_AUTHORIZATION
 } = http2.constants
 
 const { HTTP_STATUS_OK } = http2.constants
@@ -24,7 +27,13 @@ const { HTTP_STATUS_OK } = http2.constants
 export function sendPreflight(stream, methods, meta) {
 	send(stream, HTTP_STATUS_OK, {
 			[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_METHODS]: methods.join(','),
-			[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_HEADERS]: ['Authorization', HTTP2_HEADER_CONTENT_TYPE].join(','),
+			[HTTP2_HEADER_ACCESS_CONTROL_ALLOW_HEADERS]: [
+				HTTP2_HEADER_IF_MATCH,
+				HTTP2_HEADER_IF_NONE_MATCH,
+				HTTP2_HEADER_AUTHORIZATION,
+				HTTP2_HEADER_CONTENT_TYPE
+			].join(','),
 			[HTTP2_HEADER_ACCESS_CONTROL_MAX_AGE]: PREFLIGHT_AGE_SECONDS
+			// Access-Control-Allow-Credentials
 		}, undefined, undefined, meta)
 }