-
Notifications
You must be signed in to change notification settings - Fork 230
/
etag.ts
182 lines (163 loc) · 5.26 KB
/
etag.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
// Copyright 2018-2022 the oak authors. All rights reserved. MIT license.
/**
* A collection of APIs for dealing with ETags in requests and responses.
*
* @module
*/
import type { State } from "./application.ts";
import type { Context } from "./context.ts";
import { base64 } from "./deps.ts";
import type { Middleware } from "./middleware.ts";
import { BODY_TYPES, isAsyncIterable, isReader } from "./util.ts";
export interface ETagOptions {
/** Override the default behavior of calculating the `ETag`, either forcing
* a tag to be labelled weak or not. */
weak?: boolean;
}
/**
* Just the part of `Deno.FileInfo` that is required to calculate an `ETag`,
* so partial or user generated file information can be passed.
*/
export interface FileInfo {
mtime: Date | null;
size: number;
}
function isFileInfo(value: unknown): value is FileInfo {
return Boolean(
value && typeof value === "object" && "mtime" in value && "size" in value,
);
}
function calcStatTag(entity: FileInfo): string {
const mtime = entity.mtime?.getTime().toString(16) ?? "0";
const size = entity.size.toString(16);
return `"${size}-${mtime}"`;
}
const encoder = new TextEncoder();
async function calcEntityTag(entity: string | Uint8Array): Promise<string> {
if (entity.length === 0) {
return `"0-2jmj7l5rSw0yVb/vlWAYkK/YBwk="`;
}
if (typeof entity === "string") {
entity = encoder.encode(entity);
}
const hash = base64.encode(await crypto.subtle.digest("SHA-1", entity))
.substring(0, 27);
return `"${entity.length.toString(16)}-${hash}"`;
}
function fstat(file: Deno.FsFile): Promise<Deno.FileInfo | undefined> {
if ("fstat" in Deno) {
// deno-lint-ignore no-explicit-any
return (Deno as any).fstat(file.rid);
}
return Promise.resolve(undefined);
}
/** For a given Context, try to determine the response body entity that an ETag
* can be calculated from. */
// deno-lint-ignore no-explicit-any
export function getEntity<S extends State = Record<string, any>>(
context: Context<S>,
): Promise<string | Uint8Array | Deno.FileInfo | undefined> {
const { body } = context.response;
if (body instanceof Deno.FsFile) {
return fstat(body);
}
if (body instanceof Uint8Array) {
return Promise.resolve(body);
}
if (BODY_TYPES.includes(typeof body)) {
return Promise.resolve(String(body));
}
if (isAsyncIterable(body) || isReader(body)) {
return Promise.resolve(undefined);
}
if (typeof body === "object" && body !== null) {
try {
const bodyText = JSON.stringify(body);
return Promise.resolve(bodyText);
} catch {
// We don't really care about errors here
}
}
return Promise.resolve(undefined);
}
/**
* Calculate an ETag value for an entity. If the entity is `FileInfo`, then the
* tag will default to a _weak_ ETag. `options.weak` overrides any default
* behavior in generating the tag.
*
* @param entity A string, Uint8Array, or file info to use to generate the ETag
* @param options
*/
export async function calculate(
entity: string | Uint8Array | FileInfo,
options: ETagOptions = {},
): Promise<string> {
const weak = options.weak ?? isFileInfo(entity);
const tag = isFileInfo(entity)
? calcStatTag(entity)
: await calcEntityTag(entity);
return weak ? `W/${tag}` : tag;
}
/**
* Create middleware that will attempt to decode the response.body into
* something that can be used to generate an `ETag` and add the `ETag` header to
* the response.
*/
// deno-lint-ignore no-explicit-any
export function factory<S extends State = Record<string, any>>(
options?: ETagOptions,
): Middleware<S> {
return async function etag(context: Context<S>, next) {
await next();
if (!context.response.headers.has("ETag")) {
const entity = await getEntity(context);
if (entity) {
context.response.headers.set("ETag", await calculate(entity, options));
}
}
};
}
/**
* A helper function that takes the value from the `If-Match` header and an
* entity and returns `true` if the `ETag` for the entity matches the supplied
* value, otherwise `false`.
*
* See MDN's [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match)
* article for more information on how to use this function.
*/
export async function ifMatch(
value: string,
entity: string | Uint8Array | FileInfo,
options: ETagOptions = {},
): Promise<boolean> {
const etag = await calculate(entity, options);
// Weak tags cannot be matched and return false.
if (etag.startsWith("W/")) {
return false;
}
if (value.trim() === "*") {
return true;
}
const tags = value.split(/\s*,\s*/);
return tags.includes(etag);
}
/**
* A helper function that takes the value from the `If-No-Match` header and
* an entity and returns `false` if the `ETag` for the entity matches the
* supplied value, otherwise `false`.
*
* See MDN's [`If-None-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match)
* article for more information on how to use this function.
*/
export async function ifNoneMatch(
value: string,
entity: string | Uint8Array | FileInfo,
options: ETagOptions = {},
): Promise<boolean> {
if (value.trim() === "*") {
return false;
}
const etag = await calculate(entity, options);
const tags = value.split(/\s*,\s*/);
return !tags.includes(etag);
}