@johntalton/http-util 2.0.5 → 3.0.1

package/package.json

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

package/src/conditional.js

@@ -1,8 +1,47 @@
+
+/**
+ * @typedef {Object} WeakEtagItem
+ * @property {true} weak
+ * @property {false} any
+ * @property {string} etag
+ */
+
+/**
+ * @typedef {Object} AnyEtagItem
+ * @property {boolean} weak
+ * @property {true} any
+ * @property {'*'} etag
+ */
+
+/**
+ * @typedef {Object} NotWeakEtagItem
+ * @property {false} weak
+ * @property {false} any
+ * @property {string} etag
+ */
+
+/** @typedef {WeakEtagItem | NotWeakEtagItem | AnyEtagItem } EtagItem */
+
+/**
+ * @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 const CONDITION_ETAG_SEPARATOR = ','
 export const CONDITION_ETAG_ANY = '*'
 export const CONDITION_ETAG_WEAK_PREFIX = 'W/'
 export const ETAG_QUOTE = '"'
 
+/** @type {AnyEtagItem} */
+export const ANY_ETAG_ITEM = { any: true, weak: false, etag: CONDITION_ETAG_ANY }
+
 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' ]
@@ -40,26 +79,50 @@ export function isQuoted(etag) {
 	return true
 }
 
-/**
- * @typedef {Object} EtagItem
- * @property {boolean} weak
- * @property {boolean} any
- * @property {string} etag
- */
+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 }
+	}
 
-/**
- * @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
- */
+	/**
+	 * @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
+	 * @returns {string|undefined}
+	 */
+	static encodeEtag(etagItem) {
+		if(etagItem === undefined) { return undefined }
+		if(etagItem.any) {
+			if(etagItem.etag !== CONDITION_ETAG_ANY) { return undefined }
+			return CONDITION_ETAG_ANY
+		}
+
+		if(etagItem.etag === CONDITION_ETAG_ANY) { return undefined }
+		if(!isValidEtag(etagItem.etag)) { return undefined }
+
+		const prefix = etagItem.weak ? CONDITION_ETAG_WEAK_PREFIX : ''
+		return `${prefix}${ETAG_QUOTE}${etagItem.etag}${ETAG_QUOTE}`
+	}
+
 	/**
 	 * @param {string|undefined} matchHeader
 	 * @returns {Array<EtagItem>}
@@ -85,12 +148,7 @@ export class Conditional {
 				}
 			})
 			.map(item => {
-				if(item.etag === CONDITION_ETAG_ANY) {
-					return {
-						...item,
-						any: true
-					}
-				}
+				if(item.etag === CONDITION_ETAG_ANY) { return ANY_ETAG_ITEM }
 
 				// validated quoted
 				if(!isQuoted(item.etag)) { return undefined }
@@ -98,11 +156,14 @@ export class Conditional {
 				if(!isValidEtag(etag)) { return undefined }
 				if(etag === CONDITION_ETAG_ANY) { return undefined }
 
-				return {
+				/** @type {WeakEtagItem | NotWeakEtagItem} */
+				const result = {
 					weak: item.weak,
 					any: false,
 					etag
 				}
+
+				return result
 			})
 			.filter(item => item !== undefined)
 	}
@@ -187,6 +248,20 @@ export class Conditional {
 	}
 }
 
+// Ok
+// console.log(Conditional.encodeEtag({ any: true, weak: false, etag: '*' }))
+// console.log(Conditional.encodeEtag({ any: true, weak: true, etag: '*' }))
+// console.log(Conditional.encodeEtag({ any: false, weak: false, etag: 'Foo' }))
+// console.log(Conditional.encodeEtag({ any: false, weak: true, etag: 'WeakFoo' }))
+
+// Error
+// console.log(Conditional.encodeEtag(undefined))
+// console.log(Conditional.encodeEtag({ any: true, weak: false, etag: 'NotAsterisk' }))
+// console.log(Conditional.encodeEtag({ any: false, weak: false, etag: 'Foo\tBar' }))
+// console.log(Conditional.encodeEtag({ any: false, weak: false, etag: 'Foo"Bar' }))
+// console.log(Conditional.encodeEtag({ any: false, weak: false, etag: '*' }))
+
+
 // Ok
 // console.log(Conditional.parseEtagList('"bfc13a64729c4290ef5b2c2730249c88ca92d82d"'))
 // console.log(Conditional.parseEtagList('W/"67ab43", "54ed21", "7892dd"'))
@@ -225,6 +300,8 @@ export class Conditional {
 // 	}
 // }
 
+
+
 // const testBad = [
 // 	undefined,
 // 	null,

package/src/response/created.js

@@ -1,11 +1,14 @@
 import http2 from 'node:http2'
 import { send } from './send-util.js'
+import { Conditional } from '../conditional.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
+/** @import { EtagItem } from '../conditional.js' */
 
 const {
-	HTTP2_HEADER_LOCATION
+	HTTP2_HEADER_LOCATION,
+	HTTP2_HEADER_ETAG
 } = http2.constants
 
 const { HTTP_STATUS_CREATED } = http2.constants
@@ -13,10 +16,12 @@ const { HTTP_STATUS_CREATED } = http2.constants
 /**
  * @param {ServerHttp2Stream} stream
  * @param {URL} location
+ * @param {EtagItem|undefined} etag
  * @param {Metadata} meta
  */
-export function sendCreated(stream, location, meta) {
+export function sendCreated(stream, location, etag, meta) {
 	send(stream, HTTP_STATUS_CREATED, {
-			[HTTP2_HEADER_LOCATION]: location.href
+			[HTTP2_HEADER_LOCATION]: location.href,
+			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag)
 		}, undefined, undefined, meta)
 }

package/src/response/defs.js

@@ -23,7 +23,6 @@ export const PREFLIGHT_AGE_SECONDS = '500'
  * @property {Array<TimingsInfo>} performance
  * @property {string|undefined} servername
  * @property {string|undefined} origin
- * @property {string|undefined} [etag]
  */
 
 /**

package/src/response/json.js

@@ -10,9 +10,11 @@ import {
 	CONTENT_TYPE_JSON
 } from '../content-type.js'
 import { send } from './send-util.js'
+import { Conditional } from '../conditional.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
+/** @import { EtagItem } from '../conditional.js' */
 
 /** @typedef { (data: string, charset: BufferEncoding) => Buffer } EncoderFun */
 
@@ -37,9 +39,10 @@ export const ENCODER_MAP = new Map([
  * @param {ServerHttp2Stream} stream
  * @param {Object} obj
  * @param {string|undefined} encoding
+ * @param {EtagItem|undefined} etag
  * @param {Metadata} meta
  */
-export function sendJSON_Encoded(stream, obj, encoding, meta) {
+export function sendJSON_Encoded(stream, obj, encoding, etag, meta) {
 	if(stream.closed) { return }
 
 	const json = JSON.stringify(obj)
@@ -61,7 +64,7 @@ export function sendJSON_Encoded(stream, obj, encoding, meta) {
 			[HTTP2_HEADER_CONTENT_ENCODING]: actualEncoding,
 			[HTTP2_HEADER_VARY]: 'Accept, Accept-Encoding',
 			[HTTP2_HEADER_CACHE_CONTROL]: 'private',
-			[HTTP2_HEADER_ETAG]: `"${meta.etag}"`
+			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag)
 			// [HTTP2_HEADER_AGE]: age
 		}, CONTENT_TYPE_JSON, encodedData, meta)
 }

package/src/response/no-content.js

@@ -1,8 +1,10 @@
 import http2 from 'node:http2'
 import { send } from './send-util.js'
+import { Conditional } from '../conditional.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
+/** @import { EtagItem } from '../conditional.js' */
 
 const {
 	HTTP2_HEADER_ETAG
@@ -12,10 +14,11 @@ const { HTTP_STATUS_NO_CONTENT } = http2.constants
 
 /**
  * @param {ServerHttp2Stream} stream
+ * @param {EtagItem|undefined} etag
  * @param {Metadata} meta
  */
-export function sendNoContent(stream, meta) {
+export function sendNoContent(stream, etag, meta) {
 	send(stream, HTTP_STATUS_NO_CONTENT, {
-			[HTTP2_HEADER_ETAG]: `"${meta.etag}"`
+			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag)
 		}, undefined, undefined, meta)
 }

package/src/response/not-modified.js

@@ -1,8 +1,10 @@
 import http2 from 'node:http2'
 import { send } from './send-util.js'
+import { Conditional } from '../conditional.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
+/** @import { EtagItem } from '../conditional.js' */
 
 const {
 	HTTP2_HEADER_AGE,
@@ -15,14 +17,15 @@ const { HTTP_STATUS_NOT_MODIFIED } = http2.constants
 
 /**
  * @param {ServerHttp2Stream} stream
- * @param {number} age
+ * @param {EtagItem|undefined} etag
+ * @param {number|undefined} age
  * @param {Metadata} meta
  */
-export function sendNotModified(stream, age, meta) {
+export function sendNotModified(stream, etag, age, meta) {
 	send(stream, HTTP_STATUS_NOT_MODIFIED, {
 			[HTTP2_HEADER_VARY]: 'Accept, Accept-Encoding',
 			[HTTP2_HEADER_CACHE_CONTROL]: 'private',
-			[HTTP2_HEADER_ETAG]: `"${meta.etag}"`,
-			[HTTP2_HEADER_AGE]: `${age}`
+			[HTTP2_HEADER_ETAG]: Conditional.encodeEtag(etag),
+			[HTTP2_HEADER_AGE]: age !== undefined ? `${age}` : undefined
 		}, undefined, undefined, meta)
 }

package/src/response/too-many-requests.js

@@ -10,6 +10,7 @@ import { send } from './send-util.js'
 
 /** @import { ServerHttp2Stream } from 'node:http2' */
 /** @import { Metadata } from './defs.js' */
+/** @import { RateLimitInfo, RateLimitPolicyInfo } from '../rate-limit.js' */
 
 const {
 	HTTP2_HEADER_RETRY_AFTER
@@ -19,17 +20,17 @@ const { HTTP_STATUS_TOO_MANY_REQUESTS } = http2.constants
 
 /**
  * @param {ServerHttp2Stream} stream
- * @param {*} limitInfo
- * @param {Array<any>} policies
+ * @param {RateLimitInfo} limitInfo
+ * @param {Array<RateLimitPolicyInfo>} policies
  * @param {Metadata} meta
  */
 export function sendTooManyRequests(stream, limitInfo, policies, meta) {
 	send(stream, HTTP_STATUS_TOO_MANY_REQUESTS, {
-			[HTTP2_HEADER_RETRY_AFTER]: limitInfo.retryAfterS,
+			[HTTP2_HEADER_RETRY_AFTER]: `${limitInfo.resetSeconds}`,
 			[HTTP_HEADER_RATE_LIMIT]: RateLimit.from(limitInfo),
 			[HTTP_HEADER_RATE_LIMIT_POLICY]: RateLimitPolicy.from(...policies)
 		},
 		CONTENT_TYPE_TEXT,
-		`Retry After ${limitInfo.retryAfterS} Seconds`,
+		`Retry After ${limitInfo.resetSeconds} Seconds`,
 		meta)
 }