Repository: cloudflare/kv-asset-handler
Branch: main
Commit: 159d2bf184f2
Files: 25
Total size: 85.1 KB
Directory structure:
gitextract_w6nu_yq0/
├── .editorconfig
├── .gitattributes
├── .github/
│ ├── CODEOWNERS
│ ├── dependabot.yml
│ └── workflows/
│ ├── lint.yml
│ └── test.yml
├── .gitignore
├── .markdownlint.yml
├── .prettierignore
├── .prettierrc
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE_APACHE
├── LICENSE_MIT
├── README.md
├── RELEASE_CHECKLIST.md
├── package.json
├── src/
│ ├── index.ts
│ ├── mocks.ts
│ ├── test/
│ │ ├── getAssetFromKV-optional.ts
│ │ ├── getAssetFromKV.ts
│ │ ├── mapRequestToAsset.ts
│ │ └── serveSinglePageApp.ts
│ └── types.ts
└── tsconfig.json
================================================
FILE CONTENTS
================================================
================================================
FILE: .editorconfig
================================================
# https://editorconfig.org
root = true
[*]
end_of_line = lf
indent_style = tab
tab_width = 2
================================================
FILE: .gitattributes
================================================
* text=auto
* text eol=lf
================================================
FILE: .github/CODEOWNERS
================================================
# This is a comment.
# Each line is a file pattern followed by one or more owners.
* @kristianfreeman @rickyrobinett @lauragift21 @LoganGrasby @craigsdennis
================================================
FILE: .github/dependabot.yml
================================================
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "daily"
================================================
FILE: .github/workflows/lint.yml
================================================
name: Lint
on: [push, pull_request]
jobs:
prettier:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '18.x'
- name: Restore NPM cache
uses: actions/cache@v3
continue-on-error: true
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
- run: npm run lint:code
================================================
FILE: .github/workflows/test.yml
================================================
name: Run npm tests
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18.x, 20.x]
steps:
- uses: actions/checkout@v3
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- name: npm install, build, and test
run: |
npm ci
npm run build --if-present
npm test
env:
CI: true
================================================
FILE: .gitignore
================================================
node_modules
dist
================================================
FILE: .markdownlint.yml
================================================
# MD001 Header levels should only increment by one level at a time
MD001: false
# MD004 Unordered list style
MD004: false
# MD005 Inconsistent indentation for list items at the same level
MD005: false
# MD006 Consider starting bulleted lists at the beginning of the line
MD006: false
# MD007 Unordered list indentation
MD007: false
# MD013 Line length
MD013: false
# MD024 Multiple headers with the same content
MD024: false
# MD025 Multiple top level headers in the same document
MD025: false
# MD032 Lists should be surrounded by blank lines
MD032: false
# MD033 Inline HTML
MD033: false
# MD040 Fenced code blocks should have a language specified
MD040: false
================================================
FILE: .prettierignore
================================================
CHANGELOG.md
package.json
package-lock.json
dist/**/*
================================================
FILE: .prettierrc
================================================
{
"endOfLine": "lf",
"trailingComma": "all",
"singleQuote": true,
"useTabs": true,
"semi": false,
"printWidth": 100
}
================================================
FILE: CHANGELOG.md
================================================
# Changelog
## 0.3.1
- ## Maintenance
- **Remove tests from npm package to reduce npm package size - [boidolr], [pull/388]**
This PR removes the tests from the npm package, reducing the size of the package by about half.
[boidolr]: https://github.com/boidolr
[pull/388]: https://github.com/cloudflare/kv-asset-handler/pull/388
- **Bump dependencies - [Cherry], [pull/367] [pull/361] [pull/362] [pull/359] [pull/390]**
These PRs bump dependencies of the project to their latest versions.
[pull/367]: https://github.com/cloudflare/kv-asset-handler/pull/367
[pull/361]: https://github.com/cloudflare/kv-asset-handler/pull/361
[pull/362]: https://github.com/cloudflare/kv-asset-handler/pull/362
[pull/359]: https://github.com/cloudflare/kv-asset-handler/pull/359
[pull/390]: https://github.com/cloudflare/kv-asset-handler/pull/390
- **Fix README anchor links - [johtso] [pull/372]**
This PR fixes the anchor links in the README.
[johtso]: https://github.com/johtso
[pull/372]: https://github.com/cloudflare/kv-asset-handler/pull/372
## 0.3.0
- ### Features
- **Allow configurable downgrade of ETag validator strength - [awwong1], [pull/315]**
This allows users to override the default strong ETag validator behaviour to use weak ETag validators. This change allows the developer to use weak ETags and preserve 304 responses (e.g. on *.workers.dev domains).
- ### Fixes
- **Fix length property call on ArrayBuffer instance - [philipatkinson], [pull/295**]
Previously when edge cached was enabled, the `content-length` of the response was not being set correctly. This was due to the `length` property of the `ArrayBuffer` instance being called instead of the `byteLength` property. This PR fixes this issue.
- ### Maintenance
- **chore(ci): bump node versions in actions - [KianNH], [pull/354]**
This bumps the Node versions used in the CI actions to the latest LTS versions.
- **chore: use tabs for indentation - [Cherry], [pull/355]**
This PR changes the indentation of the project to use tabs instead of spaces, falling more in line with other Cloudflare JavaScript projects like wrangler.
- **chore: bump dependencies - [Cherry], [pull/356]**
This bumps many dependencies of the project to their latest versions.
## 0.2.0
- ### Features
- **Allow changing pathIsEncoded through options - [JackPriceBurns], [pull/243]**
When using `mapRequestToAsset`, it encodes the URL / key and will never check the KV store for the decoded key.
This adds the ability to set `pathIsEncoded` to true, which will decode the URL before getting it from the KV.
[jackpriceburns]: https://github.com/JackPriceBurns
[pull/243]: https://github.com/cloudflare/kv-asset-handler/pull/243
- **Support ES Modules. - [threepointone], [pull/261]**
This PR provides a possible solution for getting Workers Sites working with ES Module workers. This approach is not as invasive as other approaches, so isn't as risky either.
Usage:
```jsx
import manifestJSON from "__STATIC_CONTENT_MANIFEST";
const manifest = JSON.parse(manifestJSON);
export default {
fetch(request, env, ctx) {
return await getAssetFromKV(
{
request,
waitUntil(promise) {
return ctx.waitUntil(promise);
},
},
{
ASSET_NAMESPACE: env.ASSET_NAMESPACE,
ASSET_MANIFEST: manifest,
}
);
// ...
},
};
```
[threepointone]: https://github.com/threepointone
[pull/261]: https://github.com/cloudflare/kv-asset-handler/pull/261
- ### Fixes
- **fix: default ASSET_MANIFEST to empty object - [Cherry], [pull/254]**
As per [discussion in Discord](https://canary.discord.com/channels/595317990191398933/831143699999752262/898392183999197184) and the repo at [https://github.com/Erisa-bits/getassetfromkv-undefined-error], allowing `ASSET_MANIFEST` to be optional got lost somewhere along the years and errors when attempted to be used without it. This PR restores this functionality by setting it to an empty object (instead of `undefined`), which allows fall-through to the standard `mapRequestToAsset` function.
chore: bump dependencies - This updates a few dependencies and also pins `@types/node` to `15.x` since `16.x` has some incompatible types.
feat: generate more modern code - This removes the unnecessary async/await polyfill added by TypeScript
[cherry]: https://github.com/Cherry
[pull/254]: https://github.com/cloudflare/kv-asset-handler/pull/254
- ### Maintenance
- **chore: remove debug logs around `response.body.cancel` support - [Cherry], [pull/249]**
Fixes [issues/248]
[cherry]: https://github.com/Cherry
[pull/249]: https://github.com/cloudflare/kv-asset-handler/pull/249
[issues/248]: https://github.com/cloudflare/kv-asset-handler/issue/248
## 0.1.3
- ### Performance
- **Only parse `ASSET_MANIFEST` once on startup - [Cherry], [pull/185]**
This PR improves performance of the `getAssetFromKV` function by only parsing the asset manifest once on startup, instead of on each request. This can have a significant improvement in response times for larger sites. An example of the performance improvement with an asset manifest of over 50k files:
> Before change:
100 iterations: Done. Mean kv response time is 16.61
1000 iterations: Done. Mean kv response time is 17.798
> After change:
100 iterations: Done. Mean kv response time is 6.62
1000 iterations: Done. Mean kv response time is 7.296
Initial work and credit to [groenlid] in [pull/143].
[Cherry]: https://github.com/Cherry
[groenlid]: https://github.com/groenlid
[pull/185]: https://github.com/cloudflare/kv-asset-handler/pull/185
[pull/143]: https://github.com/cloudflare/kv-asset-handler/pull/143
- ### Fixes
- **ESM compatibility: fix crash on missing global environment variables - [ttraenkler], [pull/188]**
This PR fixes the library from crashing when global environment variables such as `__STATIC_CONTENT` and `__STATIC_CONTENT_MANIFEST` are missing, which is currently the case when using the new ESM module syntax.
Note that whilst this partially resolves the issue discussed in [issue/174], it does not provide full ESM compatibility yet. Please see [issue/174] for further discussion.
[ttraenkler]: https://github.com/ttraenkler
[pull/188]: https://github.com/cloudflare/kv-asset-handler/pull/188
[issue/174]: https://github.com/cloudflare/kv-asset-handler/issues/174
- ### Maintenance
- **Tweak GitHub Actions Workflow for proper PR testing - [Cherry], [pull/185]**
This PR tweaks the GitHub Actions Workflow to test PRs properly, both in terms of linting and the repository tests. It runs `prettier` to maintain code quality and style, and all unit tests on every PR to ensure no regressions occur.
[pull/183]: https://github.com/cloudflare/kv-asset-handler/pull/185
[Cherry]: https://github.com/Cherry
- **Add test for `mapRequestToAsset` asset override - [Cherry], [pull/186]**
This PR adds a test for the functionality added in [pull/159]. This tests that when overriding the `mapRequestToAsset` function in its entirety, this function is always run.
[pull/159]: https://github.com/cloudflare/kv-asset-handler/pull/159
[pull/186]: https://github.com/cloudflare/kv-asset-handler/pull/186
[Cherry]: https://github.com/Cherry
- **Dependabot updates**
A number of dependabot patch-level updates have been merged:
- Bump @types/node from 15.3.1 to 15.6.0 ([pull/183])
- Bump @types/node from 15.6.0 to 15.6.1 ([pull/184])
- Bump @types/node from 15.6.1 to 15.9.0 ([pull/189])
- Bump @types/node from 15.9.0 to 15.12.0 ([pull/190])
- Bump @types/node from 15.12.0 to 15.12.1 ([pull/191])
- Bump @types/node from 15.12.1 to 15.12.2 ([pull/193])
- Bump typescript from 4.2.4 to 4.3.2 ([pull/187])
- Bump prettier from 2.3.0 to 2.3.1 ([pull/192])
[pull/183]: https://github.com/cloudflare/kv-asset-handler/pull/183
[pull/184]: https://github.com/cloudflare/kv-asset-handler/pull/184
[pull/189]: https://github.com/cloudflare/kv-asset-handler/pull/189
[pull/190]: https://github.com/cloudflare/kv-asset-handler/pull/190
[pull/191]: https://github.com/cloudflare/kv-asset-handler/pull/191
[pull/193]: https://github.com/cloudflare/kv-asset-handler/pull/193
[pull/187]: https://github.com/cloudflare/kv-asset-handler/pull/187
[pull/192]: https://github.com/cloudflare/kv-asset-handler/pull/192
## 0.1.2
- ### Features
- **Support for `defaultDocument` configuration - [boemekeld], [pull/161]**
This PR adds support for customizing the `defaultDocument` option in `getAssetFromKV`. In situations where a project does not use `index.html` as the default document for a path, this can now be customized to values like `index.shtm`:
```js
return getAssetFromKV(event, {
defaultDocument: "index.shtm"
})
```
[boemekeld]: https://github.com/boemekeld
[pull/161]: https://github.com/cloudflare/kv-asset-handler/pull/161
- ### Fixes
- **Fire `mapRequestToAsset` for all requests, if explicitly defined - [Cherry], [pull/159]**
This PR fixes an issue where a custom `mapRequestToAsset` handler weren't fired if a matching asset path was found in `ASSET_MANIFEST` data. By correctly checking for this handler, we can conditionally handle any assets with this handler _even_ if they exist in the `ASSET_MANIFEST`.
**Note that this is a breaking change**, as previously, the mapRequestToAsset function was ignored if you set it, and an exact match was found in the `ASSET_MANIFEST`. That being said, this behavior was a bug, and unexpected behavior, as documented in [issue/158].
[Cherry]: https://github.com/Cherry
[issue/158]: https://github.com/cloudflare/kv-asset-handler/pull/158
[pull/159]: https://github.com/cloudflare/kv-asset-handler/pull/159
- **Etag logic refactor - [shagamemnon], [pull/133]**
This PR refactors a great deal of the Etag functionality introduced in [0.0.11](https://github.com/cloudflare/kv-asset-handler/milestone/7?closed=1). `kv-asset-handler` will now correctly set [strong and weak Etags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) both to the Cloudflare CDN and to client eyeballs, allowing for higher cache percentages with Workers Sites projects.
[pull/133]: https://github.com/cloudflare/kv-asset-handler/pull/133
[shagamemnon]: https://github.com/shagamemnon
- **Fix path decoding issue - [xiaolanglanglang], [pull/142]**
This PR improves support for non-alphanumeric character paths in `kv-asset-handler`, for instance, if the path requested is in Chinese.
[xiaolanglanglang]: https://github.com/xiaolanglanglang
[pull/142]: https://github.com/cloudflare/kv-asset-handler/pull/142
- **Check HTTP method after mapRequestToAsset - [oliverpool], [pull/178]**
This PR fixes an issue where the HTTP method for an asset is checked before the `mapRequestToAsset` handler is called. This has caused issues for users in the past, where they need to generate a `requestKey` based on an asset path, even if the request method is not `GET`. This fixes [issue/151].
[oliverpool]: https://github.com/oliverpool
[pull/178]: https://github.com/cloudflare/kv-asset-handler/pull/178
[issue/151]: https://github.com/cloudflare/kv-asset-handler/issues/151
- ### Maintenance
- **Add Markdown linting workflow to GitHub Actions - [jbampton], [pull/135]**
Our GitHub Actions workflow now includes a linting workflow for Markdown in the project, including the README, this CHANGELOG, and any other `.md` files in the source code.
[jbampton]: https://github.com/jbampton
[pull/135]: https://github.com/cloudflare/kv-asset-handler/pull/135
- **Dependabot updates**
A number of dependabot patch-level updates have been merged since our last release:
- Bump @types/node from 15.30.0 to 15.30.1 ([pull/180])
- Bump hosted-git-info from 2.8.8 to 2.8.9 ([pull/176])
- Bump ini from 1.3.5 to 1.3.8 ([pull/160])
- Bump lodash from 4.17.19 to 4.17.21 ([pull/175])
- Bump urijs from 1.19.2 to 1.19.6 ([pull/168])
- Bump y18n from 4.0.0 to 4.0.1 ([pull/173])
[pull/160]: https://github.com/cloudflare/kv-asset-handler/pull/160
[pull/168]: https://github.com/cloudflare/kv-asset-handler/pull/168
[pull/173]: https://github.com/cloudflare/kv-asset-handler/pull/173
[pull/175]: https://github.com/cloudflare/kv-asset-handler/pull/175
[pull/176]: https://github.com/cloudflare/kv-asset-handler/pull/176
[pull/180]: https://github.com/cloudflare/kv-asset-handler/pull/180
- **Repository maintenance - [Cherry], [pull/179]**
New project maintainer Cherry did a ton of maintenance in this release, improving workflows, code quality, and more. Check out the full list in [the PR][pull/179].
[Cherry]: https://github.com/Cherry
[pull/179]: https://github.com/cloudflare/kv-asset-handler/pull/179
- ### Documentation
- **Update README.md - [signalnerve], [pull/177]**
This PR adds context to our README, with mentions about _what_ this project is, how to use it, and some new things since the last version of this package: namely, [Cloudflare Pages](https://pages.dev) and the new [Cloudflare Workers Discord server](https://discord.gg/cloudflaredev)
[signalnerve]: https://github.com/signalnerve
[pull/177]: https://github.com/cloudflare/kv-asset-handler/pull/177
- **Add instructions for updating version in related repos - [caass], [pull/171]**
This PR adds instructions for updating the `kv-asset-handler` version in related repositories, such as our templates, that use `kv-asset-handler` and are exposed to end-users of Wrangler and Workers.
[caass]: https://github.com/caass
[pull/177]: https://github.com/cloudflare/kv-asset-handler/pull/171
## 0.1.1
- ### Fixes
- **kv-asset-handler can translate 206 responses to 200 - [harrishancock], [pull/166]**
Fixes [wrangler#1746](https://github.com/cloudflare/wrangler/issues/1746)
[harrishancock](https://github.com/harrishancock)
[pull/166](https://github.com/cloudflare/kv-asset-handler/pull/166)
## 0.0.12
- ### Features
- **Add defaultMimeType option to getAssetFromKV - [mgrahamjo], [pull/121]**
Some static website owners prefer not to create all of their web routes as directories containing index.html files. Instead, they prefer to create pages as extensionless HTML files. Providing a defaultMimeType option will allow users to set the Content-Type header for extensionless files to text/html, which will enable this use case.
[mgrahamjo]: https://github.com/mgrahamjo
[pull/121]: https://github.com/cloudflare/kv-asset-handler/pull/121
- **Add defaultMimeType to types - [shagamemnon], [pull/132]**
Adds the newly added defaultMimeType to the exported types for this package.
[pull/132]: https://github.com/cloudflare/kv-asset-handler/pull/132
- ### Fixes
- **Fix text/* charset - [EatonZ], [pull/130]**
Adds a missing `-` to the `utf-8` charset value in response mime types.
[EatonZ]: https://github.com/EatonZ
[pull/130]: https://github.com/cloudflare/kv-asset-handler/pull/130
- **Cache handling for HEAD requests - [klittlepage], [pull/141]**
This PR skips caching for incoming HEAD requests, as they should not be able to be edge cached.
[klittlepage]: https://github.com/klittlepage
[pull/141]: https://github.com/cloudflare/kv-asset-handler/pull/141
- ### Maintenance
- **Markdown linting/typos - [jbampton], [pull/123], [pull/125], [pull/126], [pull/127], [pull/128], [pull/129], [pull/131], [pull/134]**
These PRs contain various typo fixes and linting of existing Markdown files in our documentation and CHANGELOG.
[jbampton]: https://github.com/jbampton
[pull/123]: https://github.com/cloudflare/kv-asset-handler/pull/123
[pull/125]: https://github.com/cloudflare/kv-asset-handler/pull/125
[pull/126]: https://github.com/cloudflare/kv-asset-handler/pull/126
[pull/127]: https://github.com/cloudflare/kv-asset-handler/pull/127
[pull/128]: https://github.com/cloudflare/kv-asset-handler/pull/128
[pull/129]: https://github.com/cloudflare/kv-asset-handler/pull/129
[pull/131]: https://github.com/cloudflare/kv-asset-handler/pull/131
[pull/134]: https://github.com/cloudflare/kv-asset-handler/pull/134
## 0.0.11
- ### Features
- **Support cache revalidation using ETags and If-None-Match - [shagamemnon], [issue/62] [pull/94] [pull/113]**
Previously, cacheable resources were not looked up from the browser cache because `getAssetFromKV` would never return a `304 Not Modified` response.
Now, `getAssetFromKV` sets an `ETag` header on all cacheable assets before putting them in the Cache API, and therefore will return a `304` response when appropriate.
[shagamemnon]: https://github.com/shagamemnon
[pull/94]: https://github.com/cloudflare/kv-asset-handler/pull/94
[pull/113]: https://github.com/cloudflare/kv-asset-handler/issues/113
[issue/62]: https://github.com/cloudflare/kv-asset-handler/issues/62
- **Export TypeScript types - [ispivey], [issue/43] [pull/106]**
[ispivey]: https://github.com/ispivey
[pull/106]: https://github.com/cloudflare/kv-asset-handler/pull/106
[issue/43]: https://github.com/cloudflare/kv-asset-handler/issues/43
- ### Fixes
- **Support non-ASCII characters in paths - [SukkaW], [issue/99] [pull/105]**
Fixes an issue where non-ASCII paths were not URI-decoded before being looked up, causing non-ASCII paths to 404.
[SukkaW]: https://github.com/SukkaW
[pull/105]: https://github.com/cloudflare/kv-asset-handler/pull/105
[issue/99]: https://github.com/cloudflare/kv-asset-handler/issues/99
- **Support `charset=utf8` in MIME type - [theromis], [issue/92] [pull/97]**
Fixes an issue where `Content-Type: text/*` was never appended with `; charset=utf8`, meaning clients would not render non-ASCII characters properly.
[theromis]: https://github.com/theromis
[pull/97]: https://github.com/cloudflare/kv-asset-handler/pull/97
[issue/92]: https://github.com/cloudflare/kv-asset-handler/issues/92
- **Fix bugs in README examples - [kentonv] [bradyjoslin], [issue/93] [pull/102] [issue/88] [pull/116]**
[kentonv]: https://github.com/kentonv
[bradyjoslin]: https://github.com/bradyjoslin
[pull/102]: https://github.com/cloudflare/kv-asset-handler/pull/102
[pull/116]: https://github.com/cloudflare/kv-asset-handler/pull/116
[issue/93]: https://github.com/cloudflare/kv-asset-handler/issues/93
[issue/88]: https://github.com/cloudflare/kv-asset-handler/issues/88
- ### Maintenance
- **Make `@cloudflare/workers-types` a dependency and update deps - [ispivey], [pull/107]**
[ispivey]: https://github.com/ispivey
[pull/107]: https://github.com/cloudflare/kv-asset-handler/pull/107
- **Add Code of Conduct - [EverlastingBugstopper], [pull/101]**
[EverlastingBugstopper]: https://github.com/EverlastingBugstopper
[pull/101]: https://github.com/cloudflare/kv-asset-handler/pull/101
## 0.0.10
- ### Features
- **Allow extensionless files to be served - [victoriabernard92], [cloudflare/wrangler/issues/980], [pull/73]**
Prior to this PR, `getAssetFromKv` assumed extensionless requests (e.g. `/some-path`) would be set up to be served as the corresponding HTML file in storage (e.g. `some-path.html`).
This fix checks the `ASSET_MANIFEST` for the extensionless file name _before_ appending the HTML extension. If the extensionless file exists (e.g. `some-path` exists as a key in the ASSET_MANIFEST) then we serve that file first. If the extensionless file does not exist, then the behavior does not change (e.g. it still looks for `some-path.html`).
[victoriabernard92]: https://github.com/victoriabernard92
[cloudflare/wrangler/issues/980]: https://github.com/cloudflare/wrangler/issues/980
[pull/73]: https://github.com/cloudflare/kv-asset-handler/pull/73
- ### Fixes
- **Fix URL parsing in serveSinglePageApp - [signalnerve],[sgiacosa], [issue/72], [pull/82]**
This fixes an issue in `serveSinglePageApp` where the request.url is used as a string to retrieve static content. For example,
if a query parameter was set, the URL lookup would break. This fix uses a parsed URL instead of the string and adjusts the README.
[signalnerve]: https://github.com/signalnerve
[sgiacosa]: https://github.com/sgiacosa
[issue/72]: https://github.com/cloudflare/kv-asset-handler/issue/72
[pull/82]: https://github.com/cloudflare/kv-asset-handler/pull/82
## 0.0.9
- ### Fixes
- **Building and publishing to npm - [victoriabernard92], [pull/78], [pull/79]**
Added a `prepack` step that builds JavaScript files from the TypeScript source. This fixes previously broken `npm` publishes.
[victoriabernard92]: https://github.com/victoriabernard92
[issue/78]: https://github.com/cloudflare/kv-asset-handler/issue/78
[pull/79]: https://github.com/cloudflare/kv-asset-handler/pull/79
## 0.0.8
- ### Features
- **Support a variety of errors thrown from `getAssetFromKV` - [victoriabernard92], [issue/59] [pull/64]**
Previously, `getAssetFromKv` would throw the same error type if anything went wrong. Now it will throw different error types so that clients can catch and differentiate them.
For example, a 404 `NotFoundError` error implies nothing went wrong, the asset just didn't exist while
a 500 `InternalError` means an expected variable was undefined.
[victoriabernard92]: https://github.com/victoriabernard92
[issue/44]: https://github.com/cloudflare/kv-asset-handler/issues/44
[issue/59]: https://github.com/cloudflare/kv-asset-handler/issues/59
[pull/47]: https://github.com/cloudflare/kv-asset-handler/pull/47
- ### Fixes
- **Range Issue with Safari and videos - [victoriabernard92], [issue/60] [pull/66]**
Previously, if you wanted to serve a video from Workers KV using `kv-asset-handler`, it would be broken on Safari due to its requirement that all videos support the [`Content-Range` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range). Cloudflare already has a feature that will handle these headers automatically, we just needed to take advantage of it by passing in a `Request` object to the [Cache API](https://developers.cloudflare.com/workers/reference/apis/cache/) rather than a URL string.
videos from not including the range headers.
[victoriabernard92]: https://github.com/victoriabernard92
[shagamemnon]: https://github.com/shagamemnon
[issue/60]: https://github.com/cloudflare/kv-asset-handler/issues/60
[issue/63]: https://github.com/cloudflare/kv-asset-handler/issues/63
[pull/47]: https://github.com/cloudflare/kv-asset-handler/pull/52
[pull/66]: https://github.com/cloudflare/kv-asset-handler/pull/66
- **Support custom asset namespaces passed into `getAssetFromKV` - [victoriabernard92], [issue/67] [pull/68]**
This functionality was documented but not properly supported. Tests and implementation fixes applied.
[victoriabernard92]: https://github.com/victoriabernard92
[issue/67]: https://github.com/cloudflare/kv-asset-handler/issues/67
[pull/68]: https://github.com/cloudflare/kv-asset-handler/pull/68
## 0.0.7
- ### Features
- **Add handler for SPAs - [ashleymichal], [issue/46] [pull/47]**
Some browser applications employ client-side routers that handle navigation in the browser rather than on the server. These applications will work as expected until a non-root URL is requested from the server. This PR adds a special handler, `serveSinglePageApp`, that maps all HTML requests to the root index.html. This is similar to setting a static asset route pattern in an Express.js app.
[ashleymichal]: https://github.com/ashleymichal
[issue/46]: https://github.com/cloudflare/kv-asset-handler/issues/46
[pull/47]: https://github.com/cloudflare/kv-asset-handler/pull/47
- ### Documentation
- **Add function API for `getAssetFromKV` to README.md - [ashleymichal], [issue/48] [pull/52]**
This function, used to abstract away the implementation for retrieving static assets from a Workers KV namespace, includes a lot of great options for configuring your own, bespoke "Workers Sites" implementation. This PR adds documentation to the README for use by those who would like to tinker with these options.
[ashleymichal]: https://github.com/ashleymichal
[issue/46]: https://github.com/cloudflare/kv-asset-handler/issues/48
[pull/47]: https://github.com/cloudflare/kv-asset-handler/pull/52
## 0.0.6
- ### Fixes
- **Improve caching - [victoriabernard92], [issue/38] [pull/37]**
- Don't use browser cache by default: Previously, `kv-asset-handler` would set a `Cache-Control` header on the response sent back from the Worker to the client. After this fix, the `Cache-Control` header will only be set if `options.cacheControl.browserTTL` is set by the caller.
- Set default edge caching to 2 days: Previously the default cache time for static assets was 100 days. This PR sets the default to 2 days. This can be overridden with `options.cacheControl.edgeTTL`.
[victoriabernard92]: https://github.com/victoriabernard92
[issue/38]: https://github.com/cloudflare/kv-asset-handler/issues/38
[pull/37]: https://github.com/cloudflare/kv-asset-handler/pull/37
================================================
FILE: CODE_OF_CONDUCT.md
================================================
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or
advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[wrangler@cloudflare.com](mailto:wrangler@cloudflare.com).
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
<https://www.contributor-covenant.org/faq>. Translations are available at
<https://www.contributor-covenant.org/translations>.
================================================
FILE: LICENSE_APACHE
================================================
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
================================================
FILE: LICENSE_MIT
================================================
Copyright (c) 2018 Ashley Williams <ashley666ashley@gmail.com>
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
================================================
FILE: README.md
================================================
This repository has been archived and `@cloudflare/kv-asset-handler` has moved to [`workers-sdk`](https://github.com/cloudflare/workers-sdk). Please file any issues over in that new repository.
================================================
FILE: RELEASE_CHECKLIST.md
================================================
# Release Checklist
This is a list of the things that need to happen during a release.
## Build a Release
### Prepare the Changelog
1. Open the associated milestone. All issues and PRs should be closed. If
they are not you should reassign all open issues and PRs to future
milestones.
1. Go through the commit history since the last release. Ensure that all PRs
that have landed are marked with the milestone. You can use this to
show all the PRs that are merged on or after YYY-MM-DD:
`https://github.com/issues?q=repo%3Acloudflare%2Fkv-asset-handler+merged%3A%3E%3DYYYY-MM-DD`
1. Go through the closed PRs in the milestone.
1. Add this release to the `CHANGELOG.md`. Use the structure of previous
entries. If you use VS Code, you can use [this snippet](https://gist.github.com/victoriabernard92/296c39721a3f4b171cb55c9ab9a65ec2) to insert new changelog sections. If it is a release candidate, no official changelog is needed, but testing instructions will be added later in the process.
### Start a release PR
1. Create a new branch "#.#.#" where "#.#.#" is this release's version (release) or "#.#.#-rc.#" (release candidate)
1. Push up a commit with the `CHANGELOG.md` changes. The commit message can just be "#.#.#" (release) or "#.#.#-rc.#" (release candidate)
1. Request review from the @cloudflare/workers-devexp team.
### Review
Most of your comments will be about the changelog. Once the PR is finalized and approved...
1. If you made changes, squash or fixup all changes into a single commit.
1. Run `git push` and wait for CI to pass.
### Tag and build release
1. Once ready to merge, tag the commit by running either `git tag -a v#.#.# -m #.#.#`
1. Run `git push --tags`.
1. Wait for CI to pass.
### Edit the release
Draft a new release on the [releases page](https://github.com/cloudflare/kv-asset-handler/releases) and update release notes.
### Publish to npm
Full releases are tagged `latest`. If for some reason you mix up the commands below, follow the troubleshooting guide.
1. If this is a full release, `cd npm && npm publish`. If it is a release candidate, `cd npm && npm publish --tag beta`
1. Tweet.
### Update deps in related repos
1. Create a new branch in [worker-sites-init](https://github.com/cloudflare/worker-sites-init)
2. Update the version of `@cloudflare/kv-asset-handler` if necessary in `package.json`
3. Run `npm update`
4. Commit and create a PR
5. Repeat the process in [worker-sites-template](https://github.com/cloudflare/worker-sites-template) in the `workers-site` subdirectory
# Troubleshooting a release
Mistakes happen. Most of these release steps are recoverable if you mess up. The goal is not to, but if you find yourself cursing a fat fingered command, here are some troubleshooting tips. Please feel free to add to this guide.
## I pushed the wrong tag
Tags and releases can be removed in GitHub. First, [remove the remote tag](https://stackoverflow.com/questions/5480258/how-to-delete-a-remote-tag):
```console
git push --delete origin tagname
```
This will turn the release into a `draft` and you can delete it from the edit page.
Make sure you also delete the local tag:
```console
git tag --delete vX.X.X
```
================================================
FILE: package.json
================================================
{
"name": "@cloudflare/kv-asset-handler",
"version": "0.3.1",
"description": "Routes requests to KV assets",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"scripts": {
"prepack": "npm run build",
"build": "tsc -d",
"format": "prettier --write \"**/*.{js,ts,json,md}\"",
"pretest": "npm run build",
"lint:code": "prettier --check \"**/*.{js,ts,json,md}\"",
"lint:markdown": "markdownlint \"**/*.md\" --ignore node_modules",
"test": "ava dist/test/*.js --verbose"
},
"repository": {
"type": "git",
"url": "git+https://github.com/cloudflare/kv-asset-handler.git"
},
"keywords": [
"kv",
"cloudflare",
"workers",
"wrangler",
"assets"
],
"files": [
"src",
"dist",
"!src/test",
"!dist/test",
"LICENSE_APACHE",
"LICENSE_MIT"
],
"author": "wrangler@cloudflare.com",
"license": "MIT OR Apache-2.0",
"bugs": {
"url": "https://github.com/cloudflare/kv-asset-handler/issues"
},
"homepage": "https://github.com/cloudflare/kv-asset-handler#readme",
"dependencies": {
"mime": "^3.0.0"
},
"devDependencies": {
"@ava/typescript": "^4.1.0",
"@cloudflare/workers-types": "^4.20231218.0",
"@types/mime": "^3.0.4",
"@types/node": "^18.11.12",
"ava": "^6.0.1",
"prettier": "^3.2.2",
"service-worker-mock": "^2.0.5",
"typescript": "^5.3.3"
}
}
================================================
FILE: src/index.ts
================================================
import * as mime from 'mime'
import {
Options,
CacheControl,
MethodNotAllowedError,
NotFoundError,
InternalError,
AssetManifestType,
} from './types'
declare global {
var __STATIC_CONTENT: any, __STATIC_CONTENT_MANIFEST: string
}
const defaultCacheControl: CacheControl = {
browserTTL: null,
edgeTTL: 2 * 60 * 60 * 24, // 2 days
bypassCache: false, // do not bypass Cloudflare's cache
}
const parseStringAsObject = <T>(maybeString: string | T): T =>
typeof maybeString === 'string' ? (JSON.parse(maybeString) as T) : maybeString
const getAssetFromKVDefaultOptions: Partial<Options> = {
ASSET_NAMESPACE: typeof __STATIC_CONTENT !== 'undefined' ? __STATIC_CONTENT : undefined,
ASSET_MANIFEST:
typeof __STATIC_CONTENT_MANIFEST !== 'undefined'
? parseStringAsObject<AssetManifestType>(__STATIC_CONTENT_MANIFEST)
: {},
cacheControl: defaultCacheControl,
defaultMimeType: 'text/plain',
defaultDocument: 'index.html',
pathIsEncoded: false,
defaultETag: 'strong',
}
function assignOptions(options?: Partial<Options>): Options {
// Assign any missing options passed in to the default
// options.mapRequestToAsset is handled manually later
return <Options>Object.assign({}, getAssetFromKVDefaultOptions, options)
}
/**
* maps the path of incoming request to the request pathKey to look up
* in bucket and in cache
* e.g. for a path '/' returns '/index.html' which serves
* the content of bucket/index.html
* @param {Request} request incoming request
*/
const mapRequestToAsset = (request: Request, options?: Partial<Options>) => {
options = assignOptions(options)
const parsedUrl = new URL(request.url)
let pathname = parsedUrl.pathname
if (pathname.endsWith('/')) {
// If path looks like a directory append options.defaultDocument
// e.g. If path is /about/ -> /about/index.html
pathname = pathname.concat(options.defaultDocument)
} else if (!mime.getType(pathname)) {
// If path doesn't look like valid content
// e.g. /about.me -> /about.me/index.html
pathname = pathname.concat('/' + options.defaultDocument)
}
parsedUrl.pathname = pathname
return new Request(parsedUrl.toString(), request)
}
/**
* maps the path of incoming request to /index.html if it evaluates to
* any HTML file.
* @param {Request} request incoming request
*/
function serveSinglePageApp(request: Request, options?: Partial<Options>): Request {
options = assignOptions(options)
// First apply the default handler, which already has logic to detect
// paths that should map to HTML files.
request = mapRequestToAsset(request, options)
const parsedUrl = new URL(request.url)
// Detect if the default handler decided to map to
// a HTML file in some specific directory.
if (parsedUrl.pathname.endsWith('.html')) {
// If expected HTML file was missing, just return the root index.html (or options.defaultDocument)
return new Request(`${parsedUrl.origin}/${options.defaultDocument}`, request)
} else {
// The default handler decided this is not an HTML page. It's probably
// an image, CSS, or JS file. Leave it as-is.
return request
}
}
/**
* takes the path of the incoming request, gathers the appropriate content from KV, and returns
* the response
*
* @param {FetchEvent} event the fetch event of the triggered request
* @param {{mapRequestToAsset: (string: Request) => Request, cacheControl: {bypassCache:boolean, edgeTTL: number, browserTTL:number}, ASSET_NAMESPACE: any, ASSET_MANIFEST:any}} [options] configurable options
* @param {CacheControl} [options.cacheControl] determine how to cache on Cloudflare and the browser
* @param {typeof(options.mapRequestToAsset)} [options.mapRequestToAsset] maps the path of incoming request to the request pathKey to look up
* @param {Object | string} [options.ASSET_NAMESPACE] the binding to the namespace that script references
* @param {any} [options.ASSET_MANIFEST] the map of the key to cache and store in KV
* */
type Evt = {
request: Request
waitUntil: (promise: Promise<any>) => void
}
const getAssetFromKV = async (event: Evt, options?: Partial<Options>): Promise<Response> => {
options = assignOptions(options)
const request = event.request
const ASSET_NAMESPACE = options.ASSET_NAMESPACE
const ASSET_MANIFEST = parseStringAsObject<AssetManifestType>(options.ASSET_MANIFEST)
if (typeof ASSET_NAMESPACE === 'undefined') {
throw new InternalError(`there is no KV namespace bound to the script`)
}
const rawPathKey = new URL(request.url).pathname.replace(/^\/+/, '') // strip any preceding /'s
let pathIsEncoded = options.pathIsEncoded
let requestKey
// if options.mapRequestToAsset is explicitly passed in, always use it and assume user has own intentions
// otherwise handle request as normal, with default mapRequestToAsset below
if (options.mapRequestToAsset) {
requestKey = options.mapRequestToAsset(request)
} else if (ASSET_MANIFEST[rawPathKey]) {
requestKey = request
} else if (ASSET_MANIFEST[decodeURIComponent(rawPathKey)]) {
pathIsEncoded = true
requestKey = request
} else {
const mappedRequest = mapRequestToAsset(request)
const mappedRawPathKey = new URL(mappedRequest.url).pathname.replace(/^\/+/, '')
if (ASSET_MANIFEST[decodeURIComponent(mappedRawPathKey)]) {
pathIsEncoded = true
requestKey = mappedRequest
} else {
// use default mapRequestToAsset
requestKey = mapRequestToAsset(request, options)
}
}
const SUPPORTED_METHODS = ['GET', 'HEAD']
if (!SUPPORTED_METHODS.includes(requestKey.method)) {
throw new MethodNotAllowedError(`${requestKey.method} is not a valid request method`)
}
const parsedUrl = new URL(requestKey.url)
const pathname = pathIsEncoded ? decodeURIComponent(parsedUrl.pathname) : parsedUrl.pathname // decode percentage encoded path only when necessary
// pathKey is the file path to look up in the manifest
let pathKey = pathname.replace(/^\/+/, '') // remove prepended /
// @ts-ignore
const cache = caches.default
let mimeType = mime.getType(pathKey) || options.defaultMimeType
if (mimeType.startsWith('text') || mimeType === 'application/javascript') {
mimeType += '; charset=utf-8'
}
let shouldEdgeCache = false // false if storing in KV by raw file path i.e. no hash
// check manifest for map from file path to hash
if (typeof ASSET_MANIFEST !== 'undefined') {
if (ASSET_MANIFEST[pathKey]) {
pathKey = ASSET_MANIFEST[pathKey]
// if path key is in asset manifest, we can assume it contains a content hash and can be cached
shouldEdgeCache = true
}
}
// TODO this excludes search params from cache, investigate ideal behavior
let cacheKey = new Request(`${parsedUrl.origin}/${pathKey}`, request)
// if argument passed in for cacheControl is a function then
// evaluate that function. otherwise return the Object passed in
// or default Object
const evalCacheOpts = (() => {
switch (typeof options.cacheControl) {
case 'function':
return options.cacheControl(request)
case 'object':
return options.cacheControl
default:
return defaultCacheControl
}
})()
// formats the etag depending on the response context. if the entityId
// is invalid, returns an empty string (instead of null) to prevent the
// the potentially disastrous scenario where the value of the Etag resp
// header is "null". Could be modified in future to base64 encode etc
const formatETag = (entityId: any = pathKey, validatorType: string = options.defaultETag) => {
if (!entityId) {
return ''
}
switch (validatorType) {
case 'weak':
if (!entityId.startsWith('W/')) {
if (entityId.startsWith(`"`) && entityId.endsWith(`"`)) {
return `W/${entityId}`
}
return `W/"${entityId}"`
}
return entityId
case 'strong':
if (entityId.startsWith(`W/"`)) {
entityId = entityId.replace('W/', '')
}
if (!entityId.endsWith(`"`)) {
entityId = `"${entityId}"`
}
return entityId
default:
return ''
}
}
options.cacheControl = Object.assign({}, defaultCacheControl, evalCacheOpts)
// override shouldEdgeCache if options say to bypassCache
if (
options.cacheControl.bypassCache ||
options.cacheControl.edgeTTL === null ||
request.method == 'HEAD'
) {
shouldEdgeCache = false
}
// only set max-age if explicitly passed in a number as an arg
const shouldSetBrowserCache = typeof options.cacheControl.browserTTL === 'number'
let response = null
if (shouldEdgeCache) {
response = await cache.match(cacheKey)
}
if (response) {
if (response.status > 300 && response.status < 400) {
if (response.body && 'cancel' in Object.getPrototypeOf(response.body)) {
// Body exists and environment supports readable streams
response.body.cancel()
} else {
// Environment doesnt support readable streams, or null repsonse body. Nothing to do
}
response = new Response(null, response)
} else {
// fixes #165
let opts = {
headers: new Headers(response.headers),
status: 0,
statusText: '',
}
opts.headers.set('cf-cache-status', 'HIT')
if (response.status) {
opts.status = response.status
opts.statusText = response.statusText
} else if (opts.headers.has('Content-Range')) {
opts.status = 206
opts.statusText = 'Partial Content'
} else {
opts.status = 200
opts.statusText = 'OK'
}
response = new Response(response.body, opts)
}
} else {
const body = await ASSET_NAMESPACE.get(pathKey, 'arrayBuffer')
if (body === null) {
throw new NotFoundError(`could not find ${pathKey} in your content namespace`)
}
response = new Response(body)
if (shouldEdgeCache) {
response.headers.set('Accept-Ranges', 'bytes')
response.headers.set('Content-Length', String(body.byteLength))
// set etag before cache insertion
if (!response.headers.has('etag')) {
response.headers.set('etag', formatETag(pathKey))
}
// determine Cloudflare cache behavior
response.headers.set('Cache-Control', `max-age=${options.cacheControl.edgeTTL}`)
event.waitUntil(cache.put(cacheKey, response.clone()))
response.headers.set('CF-Cache-Status', 'MISS')
}
}
response.headers.set('Content-Type', mimeType)
if (response.status === 304) {
let etag = formatETag(response.headers.get('etag'))
let ifNoneMatch = cacheKey.headers.get('if-none-match')
let proxyCacheStatus = response.headers.get('CF-Cache-Status')
if (etag) {
if (ifNoneMatch && ifNoneMatch === etag && proxyCacheStatus === 'MISS') {
response.headers.set('CF-Cache-Status', 'EXPIRED')
} else {
response.headers.set('CF-Cache-Status', 'REVALIDATED')
}
response.headers.set('etag', formatETag(etag, 'weak'))
}
}
if (shouldSetBrowserCache) {
response.headers.set('Cache-Control', `max-age=${options.cacheControl.browserTTL}`)
} else {
response.headers.delete('Cache-Control')
}
return response
}
export { getAssetFromKV, mapRequestToAsset, serveSinglePageApp }
export { Options, CacheControl, MethodNotAllowedError, NotFoundError, InternalError }
================================================
FILE: src/mocks.ts
================================================
const makeServiceWorkerEnv = require('service-worker-mock')
const HASH = '123HASHBROWN'
export const getEvent = (request: Request): any => {
const waitUntil = async (callback: any) => {
await callback
}
return {
request,
waitUntil,
}
}
const store: any = {
'key1.123HASHBROWN.txt': 'val1',
'key1.123HASHBROWN.png': 'val1',
'index.123HASHBROWN.html': 'index.html',
'cache.123HASHBROWN.html': 'cache me if you can',
'测试.123HASHBROWN.html': 'My filename is non-ascii',
'%not-really-percent-encoded.123HASHBROWN.html': 'browser percent encoded',
'%2F.123HASHBROWN.html': 'user percent encoded',
'你好.123HASHBROWN.html': 'I shouldnt be served',
'%E4%BD%A0%E5%A5%BD.123HASHBROWN.html': 'Im important',
'nohash.txt': 'no hash but still got some result',
'sub/blah.123HASHBROWN.png': 'picturedis',
'sub/index.123HASHBROWN.html': 'picturedis',
'client.123HASHBROWN': 'important file',
'client.123HASHBROWN/index.html': 'Im here but serve my big bro above',
'image.123HASHBROWN.png': 'imagepng',
'image.123HASHBROWN.webp': 'imagewebp',
'你好/index.123HASHBROWN.html': 'My path is non-ascii',
}
export const mockKV = (store: any) => {
return {
get: (path: string) => store[path] || null,
}
}
export const mockManifest = () => {
return JSON.stringify({
'key1.txt': `key1.${HASH}.txt`,
'key1.png': `key1.${HASH}.png`,
'cache.html': `cache.${HASH}.html`,
'测试.html': `测试.${HASH}.html`,
'你好.html': `你好.${HASH}.html`,
'%not-really-percent-encoded.html': `%not-really-percent-encoded.${HASH}.html`,
'%2F.html': `%2F.${HASH}.html`,
'%E4%BD%A0%E5%A5%BD.html': `%E4%BD%A0%E5%A5%BD.${HASH}.html`,
'index.html': `index.${HASH}.html`,
'sub/blah.png': `sub/blah.${HASH}.png`,
'sub/index.html': `sub/index.${HASH}.html`,
client: `client.${HASH}`,
'client/index.html': `client.${HASH}`,
'image.png': `image.${HASH}.png`,
'image.webp': `image.${HASH}.webp`,
'你好/index.html': `你好/index.${HASH}.html`,
})
}
let cacheStore: any = new Map()
interface CacheKey {
url: object
headers: object
}
export const mockCaches = () => {
return {
default: {
async match(key: any) {
let cacheKey: CacheKey = {
url: key.url,
headers: {},
}
let response
if (key.headers.has('if-none-match')) {
let makeStrongEtag = key.headers.get('if-none-match').replace('W/', '')
Reflect.set(cacheKey.headers, 'etag', makeStrongEtag)
response = cacheStore.get(JSON.stringify(cacheKey))
} else {
// if client doesn't send if-none-match, we need to iterate through these keys
// and just test the URL
const activeCacheKeys: Array<string> = Array.from(cacheStore.keys())
for (const cacheStoreKey of activeCacheKeys) {
if (JSON.parse(cacheStoreKey).url === key.url) {
response = cacheStore.get(cacheStoreKey)
}
}
}
// TODO: write test to accomodate for rare scenarios with where range requests accomodate etags
if (response && !key.headers.has('if-none-match')) {
// this appears overly verbose, but is necessary to document edge cache behavior
// The Range request header triggers the response header Content-Range ...
const range = key.headers.get('range')
if (range) {
response.headers.set(
'content-range',
`bytes ${range.split('=').pop()}/${response.headers.get('content-length')}`,
)
}
// ... which we are using in this repository to set status 206
if (response.headers.has('content-range')) {
response.status = 206
} else {
response.status = 200
}
let etag = response.headers.get('etag')
if (etag && !etag.includes('W/')) {
response.headers.set('etag', `W/${etag}`)
}
}
return response
},
async put(key: any, val: Response) {
let headers = new Headers(val.headers)
let url = new URL(key.url)
let resWithBody = new Response(val.body, { headers, status: 200 })
let resNoBody = new Response(null, { headers, status: 304 })
let cacheKey: CacheKey = {
url: key.url,
headers: {
etag: `"${url.pathname.replace('/', '')}"`,
},
}
cacheStore.set(JSON.stringify(cacheKey), resNoBody)
cacheKey.headers = {}
cacheStore.set(JSON.stringify(cacheKey), resWithBody)
return
},
},
}
}
// mocks functionality used inside worker request
export function mockRequestScope() {
Object.assign(global, makeServiceWorkerEnv())
Object.assign(global, { __STATIC_CONTENT_MANIFEST: mockManifest() })
Object.assign(global, { __STATIC_CONTENT: mockKV(store) })
Object.assign(global, { caches: mockCaches() })
}
// mocks functionality used on global isolate scope. such as the KV namespace bind
export function mockGlobalScope() {
Object.assign(global, { __STATIC_CONTENT_MANIFEST: mockManifest() })
Object.assign(global, { __STATIC_CONTENT: mockKV(store) })
}
export const sleep = (milliseconds: number) => {
return new Promise((resolve) => setTimeout(resolve, milliseconds))
}
================================================
FILE: src/test/getAssetFromKV-optional.ts
================================================
import test from 'ava'
import { mockRequestScope, mockGlobalScope, getEvent, sleep, mockKV, mockManifest } from '../mocks'
mockGlobalScope()
// manually reset manifest global, to test optional behaviour
Object.assign(global, { __STATIC_CONTENT_MANIFEST: undefined })
import { getAssetFromKV, mapRequestToAsset } from '../index'
test('getAssetFromKV return correct val from KV without manifest', async (t) => {
mockRequestScope()
// manually reset manifest global, to test optional behaviour
Object.assign(global, { __STATIC_CONTENT_MANIFEST: undefined })
const event = getEvent(new Request('https://blah.com/key1.123HASHBROWN.txt'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'val1')
t.true(res.headers.get('content-type').includes('text'))
} else {
t.fail('Response was undefined')
}
})
================================================
FILE: src/test/getAssetFromKV.ts
================================================
import test from 'ava'
import { mockRequestScope, mockGlobalScope, getEvent, sleep, mockKV, mockManifest } from '../mocks'
mockGlobalScope()
import { getAssetFromKV, mapRequestToAsset } from '../index'
import { KVError } from '../types'
test('getAssetFromKV return correct val from KV and default caching', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/key1.txt'))
const res = await getAssetFromKV(event)
if (res) {
t.is(res.headers.get('cache-control'), null)
t.is(res.headers.get('cf-cache-status'), 'MISS')
t.is(await res.text(), 'val1')
t.true(res.headers.get('content-type').includes('text'))
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV evaluated the file matching the extensionless path first /client/ -> client', async (t) => {
mockRequestScope()
const event = getEvent(new Request(`https://foo.com/client/`))
const res = await getAssetFromKV(event)
t.is(await res.text(), 'important file')
t.true(res.headers.get('content-type').includes('text'))
})
test('getAssetFromKV evaluated the file matching the extensionless path first /client -> client', async (t) => {
mockRequestScope()
const event = getEvent(new Request(`https://foo.com/client`))
const res = await getAssetFromKV(event)
t.is(await res.text(), 'important file')
t.true(res.headers.get('content-type').includes('text'))
})
test('getAssetFromKV if not in asset manifest still returns nohash.txt', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/nohash.txt'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'no hash but still got some result')
t.true(res.headers.get('content-type').includes('text'))
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV if no asset manifest /client -> client fails', async (t) => {
mockRequestScope()
const event = getEvent(new Request(`https://foo.com/client`))
const error: KVError = await t.throwsAsync(getAssetFromKV(event, { ASSET_MANIFEST: {} }))
t.is(error.status, 404)
})
test('getAssetFromKV if sub/ -> sub/index.html served', async (t) => {
mockRequestScope()
const event = getEvent(new Request(`https://foo.com/sub`))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'picturedis')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV gets index.html by default for / requests', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'index.html')
t.true(res.headers.get('content-type').includes('html'))
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV non ASCII path support', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/测试.html'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'My filename is non-ascii')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV supports browser percent encoded URLs', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://example.com/%not-really-percent-encoded.html'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'browser percent encoded')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV supports user percent encoded URLs', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/%2F.html'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'user percent encoded')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV only decode URL when necessary', async (t) => {
mockRequestScope()
const event1 = getEvent(new Request('https://blah.com/%E4%BD%A0%E5%A5%BD.html'))
const event2 = getEvent(new Request('https://blah.com/你好.html'))
const res1 = await getAssetFromKV(event1)
const res2 = await getAssetFromKV(event2)
if (res1 && res2) {
t.is(await res1.text(), 'Im important')
t.is(await res2.text(), 'Im important')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV Support for user decode url path', async (t) => {
mockRequestScope()
const event1 = getEvent(new Request('https://blah.com/%E4%BD%A0%E5%A5%BD/'))
const event2 = getEvent(new Request('https://blah.com/你好/'))
const res1 = await getAssetFromKV(event1)
const res2 = await getAssetFromKV(event2)
if (res1 && res2) {
t.is(await res1.text(), 'My path is non-ascii')
t.is(await res2.text(), 'My path is non-ascii')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV custom key modifier', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/docs/sub/blah.png'))
const customRequestMapper = (request: Request) => {
let defaultModifiedRequest = mapRequestToAsset(request)
let url = new URL(defaultModifiedRequest.url)
url.pathname = url.pathname.replace('/docs', '')
return new Request(url.toString(), request)
}
const res = await getAssetFromKV(event, { mapRequestToAsset: customRequestMapper })
if (res) {
t.is(await res.text(), 'picturedis')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV request override with existing manifest file', async (t) => {
// see https://github.com/cloudflare/kv-asset-handler/pull/159 for more info
mockRequestScope()
const event = getEvent(new Request('https://blah.com/image.png')) // real file in manifest
const customRequestMapper = (request: Request) => {
let defaultModifiedRequest = mapRequestToAsset(request)
let url = new URL(defaultModifiedRequest.url)
url.pathname = '/image.webp' // other different file in manifest
return new Request(url.toString(), request)
}
const res = await getAssetFromKV(event, { mapRequestToAsset: customRequestMapper })
if (res) {
t.is(await res.text(), 'imagewebp')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV when setting browser caching', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/'))
const res = await getAssetFromKV(event, { cacheControl: { browserTTL: 22 } })
if (res) {
t.is(res.headers.get('cache-control'), 'max-age=22')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV when setting custom cache setting', async (t) => {
mockRequestScope()
const event1 = getEvent(new Request('https://blah.com/'))
const event2 = getEvent(new Request('https://blah.com/key1.png?blah=34'))
const cacheOnlyPngs = (req: Request) => {
if (new URL(req.url).pathname.endsWith('.png'))
return {
browserTTL: 720,
edgeTTL: 720,
}
else
return {
bypassCache: true,
}
}
const res1 = await getAssetFromKV(event1, { cacheControl: cacheOnlyPngs })
const res2 = await getAssetFromKV(event2, { cacheControl: cacheOnlyPngs })
if (res1 && res2) {
t.is(res1.headers.get('cache-control'), null)
t.true(res2.headers.get('content-type').includes('png'))
t.is(res2.headers.get('cache-control'), 'max-age=720')
t.is(res2.headers.get('cf-cache-status'), 'MISS')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV caches on two sequential requests', async (t) => {
mockRequestScope()
const resourceKey = 'cache.html'
const resourceVersion = JSON.parse(mockManifest())[resourceKey]
const event1 = getEvent(new Request(`https://blah.com/${resourceKey}`))
const event2 = getEvent(
new Request(`https://blah.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}"`,
},
}),
)
const res1 = await getAssetFromKV(event1, { cacheControl: { edgeTTL: 720, browserTTL: 720 } })
await sleep(1)
const res2 = await getAssetFromKV(event2)
if (res1 && res2) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res1.headers.get('cache-control'), 'max-age=720')
t.is(res2.headers.get('cf-cache-status'), 'REVALIDATED')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV does not store max-age on two sequential requests', async (t) => {
mockRequestScope()
const resourceKey = 'cache.html'
const resourceVersion = JSON.parse(mockManifest())[resourceKey]
const event1 = getEvent(new Request(`https://blah.com/${resourceKey}`))
const event2 = getEvent(
new Request(`https://blah.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}"`,
},
}),
)
const res1 = await getAssetFromKV(event1, { cacheControl: { edgeTTL: 720 } })
await sleep(100)
const res2 = await getAssetFromKV(event2)
if (res1 && res2) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res1.headers.get('cache-control'), null)
t.is(res2.headers.get('cf-cache-status'), 'REVALIDATED')
t.is(res2.headers.get('cache-control'), null)
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV does not cache on Cloudflare when bypass cache set', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/'))
const res = await getAssetFromKV(event, { cacheControl: { bypassCache: true } })
if (res) {
t.is(res.headers.get('cache-control'), null)
t.is(res.headers.get('cf-cache-status'), null)
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV with no trailing slash on root', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'index.html')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV with no trailing slash on a subdirectory', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/sub/blah.png'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'picturedis')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV no result throws an error', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/random'))
const error: KVError = await t.throwsAsync(getAssetFromKV(event))
t.is(error.status, 404)
})
test('getAssetFromKV TTls set to null should not cache on browser or edge', async (t) => {
mockRequestScope()
const event = getEvent(new Request('https://blah.com/'))
const res1 = await getAssetFromKV(event, { cacheControl: { browserTTL: null, edgeTTL: null } })
await sleep(100)
const res2 = await getAssetFromKV(event, { cacheControl: { browserTTL: null, edgeTTL: null } })
if (res1 && res2) {
t.is(res1.headers.get('cf-cache-status'), null)
t.is(res1.headers.get('cache-control'), null)
t.is(res2.headers.get('cf-cache-status'), null)
t.is(res2.headers.get('cache-control'), null)
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV passing in a custom NAMESPACE serves correct asset', async (t) => {
mockRequestScope()
let CUSTOM_NAMESPACE = mockKV({
'key1.123HASHBROWN.txt': 'val1',
})
Object.assign(global, { CUSTOM_NAMESPACE })
const event = getEvent(new Request('https://blah.com/'))
const res = await getAssetFromKV(event)
if (res) {
t.is(await res.text(), 'index.html')
t.true(res.headers.get('content-type').includes('html'))
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV when custom namespace without the asset should fail', async (t) => {
mockRequestScope()
let CUSTOM_NAMESPACE = mockKV({
'key5.123HASHBROWN.txt': 'customvalu',
})
const event = getEvent(new Request('https://blah.com'))
const error: KVError = await t.throwsAsync(
getAssetFromKV(event, { ASSET_NAMESPACE: CUSTOM_NAMESPACE }),
)
t.is(error.status, 404)
})
test('getAssetFromKV when namespace not bound fails', async (t) => {
mockRequestScope()
var MY_CUSTOM_NAMESPACE = undefined
Object.assign(global, { MY_CUSTOM_NAMESPACE })
const event = getEvent(new Request('https://blah.com/'))
const error: KVError = await t.throwsAsync(
getAssetFromKV(event, { ASSET_NAMESPACE: MY_CUSTOM_NAMESPACE }),
)
t.is(error.status, 500)
})
test('getAssetFromKV when if-none-match === active resource version, should revalidate', async (t) => {
mockRequestScope()
const resourceKey = 'key1.png'
const resourceVersion = JSON.parse(mockManifest())[resourceKey]
const event1 = getEvent(new Request(`https://blah.com/${resourceKey}`))
const event2 = getEvent(
new Request(`https://blah.com/${resourceKey}`, {
headers: {
'if-none-match': `W/"${resourceVersion}"`,
},
}),
)
const res1 = await getAssetFromKV(event1, { cacheControl: { edgeTTL: 720 } })
await sleep(100)
const res2 = await getAssetFromKV(event2)
if (res1 && res2) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res2.headers.get('cf-cache-status'), 'REVALIDATED')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV when if-none-match equals etag of stale resource then should bypass cache', async (t) => {
mockRequestScope()
const resourceKey = 'key1.png'
const resourceVersion = JSON.parse(mockManifest())[resourceKey]
const req1 = new Request(`https://blah.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}"`,
},
})
const req2 = new Request(`https://blah.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}-another-version"`,
},
})
const event = getEvent(req1)
const event2 = getEvent(req2)
const res1 = await getAssetFromKV(event, { cacheControl: { edgeTTL: 720 } })
const res2 = await getAssetFromKV(event)
const res3 = await getAssetFromKV(event2)
if (res1 && res2 && res3) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res2.headers.get('etag'), `W/${req1.headers.get('if-none-match')}`)
t.is(res2.headers.get('cf-cache-status'), 'REVALIDATED')
t.not(res3.headers.get('etag'), req2.headers.get('if-none-match'))
t.is(res3.headers.get('cf-cache-status'), 'MISS')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV when resource in cache, etag should be weakened before returned to eyeball', async (t) => {
mockRequestScope()
const resourceKey = 'key1.png'
const resourceVersion = JSON.parse(mockManifest())[resourceKey]
const req1 = new Request(`https://blah.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}"`,
},
})
const event = getEvent(req1)
const res1 = await getAssetFromKV(event, { cacheControl: { edgeTTL: 720 } })
const res2 = await getAssetFromKV(event)
if (res1 && res2) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res2.headers.get('etag'), `W/${req1.headers.get('if-none-match')}`)
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV should support weak etag override of resource', async (t) => {
mockRequestScope()
const resourceKey = 'key1.png'
const resourceVersion = JSON.parse(mockManifest())[resourceKey]
const req1 = new Request(`https://blah-weak.com/${resourceKey}`, {
headers: {
'if-none-match': `W/"${resourceVersion}"`,
},
})
const req2 = new Request(`https://blah-weak.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}"`,
},
})
const req3 = new Request(`https://blah-weak.com/${resourceKey}`, {
headers: {
'if-none-match': `"${resourceVersion}-another-version"`,
},
})
const event1 = getEvent(req1)
const event2 = getEvent(req2)
const event3 = getEvent(req3)
const res1 = await getAssetFromKV(event1, { defaultETag: 'weak' })
const res2 = await getAssetFromKV(event2, { defaultETag: 'weak' })
const res3 = await getAssetFromKV(event3, { defaultETag: 'weak' })
if (res1 && res2 && res3) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res1.headers.get('etag'), req1.headers.get('if-none-match'))
t.is(res2.headers.get('cf-cache-status'), 'REVALIDATED')
t.is(res2.headers.get('etag'), `W/${req2.headers.get('if-none-match')}`)
t.is(res3.headers.get('cf-cache-status'), 'MISS')
t.not(res3.headers.get('etag'), req2.headers.get('if-none-match'))
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV if-none-match not sent but resource in cache, should return cache hit 200 OK', async (t) => {
const resourceKey = 'cache.html'
const event = getEvent(new Request(`https://blah.com/${resourceKey}`))
const res1 = await getAssetFromKV(event, { cacheControl: { edgeTTL: 720 } })
await sleep(1)
const res2 = await getAssetFromKV(event)
if (res1 && res2) {
t.is(res1.headers.get('cf-cache-status'), 'MISS')
t.is(res1.headers.get('cache-control'), null)
t.is(res2.status, 200)
t.is(res2.headers.get('cf-cache-status'), 'HIT')
} else {
t.fail('Response was undefined')
}
})
test('getAssetFromKV if range request submitted and resource in cache, request fulfilled', async (t) => {
const resourceKey = 'cache.html'
const event1 = getEvent(new Request(`https://blah.com/${resourceKey}`))
const event2 = getEvent(
new Request(`https://blah.com/${resourceKey}`, { headers: { range: 'bytes=0-10' } }),
)
const res1 = getAssetFromKV(event1, { cacheControl: { edgeTTL: 720 } })
await res1
await sleep(2)
const res2 = await getAssetFromKV(event2)
if (res2.headers.has('content-range')) {
t.is(res2.status, 206)
} else {
t.fail('Response was undefined')
}
})
test.todo('getAssetFromKV when body not empty, should invoke .cancel()')
================================================
FILE: src/test/mapRequestToAsset.ts
================================================
import test from 'ava'
import { mockRequestScope, mockGlobalScope } from '../mocks'
mockGlobalScope()
import { mapRequestToAsset } from '../index'
test('mapRequestToAsset() correctly changes /about -> /about/index.html', async (t) => {
mockRequestScope()
let path = '/about'
let request = new Request(`https://foo.com${path}`)
let newRequest = mapRequestToAsset(request)
t.is(newRequest.url, request.url + '/index.html')
})
test('mapRequestToAsset() correctly changes /about/ -> /about/index.html', async (t) => {
mockRequestScope()
let path = '/about/'
let request = new Request(`https://foo.com${path}`)
let newRequest = mapRequestToAsset(request)
t.is(newRequest.url, request.url + 'index.html')
})
test('mapRequestToAsset() correctly changes /about.me/ -> /about.me/index.html', async (t) => {
mockRequestScope()
let path = '/about.me/'
let request = new Request(`https://foo.com${path}`)
let newRequest = mapRequestToAsset(request)
t.is(newRequest.url, request.url + 'index.html')
})
test('mapRequestToAsset() correctly changes /about -> /about/default.html', async (t) => {
mockRequestScope()
let path = '/about'
let request = new Request(`https://foo.com${path}`)
let newRequest = mapRequestToAsset(request, { defaultDocument: 'default.html' })
t.is(newRequest.url, request.url + '/default.html')
})
================================================
FILE: src/test/serveSinglePageApp.ts
================================================
import test from 'ava'
import { mockRequestScope, mockGlobalScope } from '../mocks'
mockGlobalScope()
import { serveSinglePageApp } from '../index'
function testRequest(path: string) {
mockRequestScope()
let url = new URL('https://example.com')
url.pathname = path
let request = new Request(url.toString())
return request
}
test('serveSinglePageApp returns root asset path when request path ends in .html', async (t) => {
let path = '/foo/thing.html'
let request = testRequest(path)
let expected_request = testRequest('/index.html')
let actual_request = serveSinglePageApp(request)
t.deepEqual(expected_request, actual_request)
})
test('serveSinglePageApp returns root asset path when request path does not have extension', async (t) => {
let path = '/foo/thing'
let request = testRequest(path)
let expected_request = testRequest('/index.html')
let actual_request = serveSinglePageApp(request)
t.deepEqual(expected_request, actual_request)
})
test('serveSinglePageApp returns requested asset when request path has non-html extension', async (t) => {
let path = '/foo/thing.js'
let request = testRequest(path)
let expected_request = request
let actual_request = serveSinglePageApp(request)
t.deepEqual(expected_request, actual_request)
})
================================================
FILE: src/types.ts
================================================
export type CacheControl = {
browserTTL: number
edgeTTL: number
bypassCache: boolean
}
export type AssetManifestType = Record<string, string>
export type Options = {
cacheControl: ((req: Request) => Partial<CacheControl>) | Partial<CacheControl>
ASSET_NAMESPACE: any
ASSET_MANIFEST: AssetManifestType | string
mapRequestToAsset?: (req: Request, options?: Partial<Options>) => Request
defaultMimeType: string
defaultDocument: string
pathIsEncoded: boolean
defaultETag: 'strong' | 'weak'
}
export class KVError extends Error {
constructor(message?: string, status: number = 500) {
super(message)
// see: typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html
Object.setPrototypeOf(this, new.target.prototype) // restore prototype chain
this.name = KVError.name // stack traces display correctly now
this.status = status
}
status: number
}
export class MethodNotAllowedError extends KVError {
constructor(message: string = `Not a valid request method`, status: number = 405) {
super(message, status)
}
}
export class NotFoundError extends KVError {
constructor(message: string = `Not Found`, status: number = 404) {
super(message, status)
}
}
export class InternalError extends KVError {
constructor(message: string = `Internal Error in KV Asset Handler`, status: number = 500) {
super(message, status)
}
}
================================================
FILE: tsconfig.json
================================================
{
"compilerOptions": {
"outDir": "./dist",
"noImplicitAny": true,
"target": "ES2017",
"allowJs": false,
"lib": ["WebWorker", "ES5", "ScriptHost"],
"module": "commonjs",
"moduleResolution": "node"
},
"include": ["./src/*.ts", "./src/**/*.ts", "./test/**/*.ts", "./test/*.ts", "./src/types.d.ts"],
"exclude": ["node_modules/", "dist/"]
}
gitextract_w6nu_yq0/ ├── .editorconfig ├── .gitattributes ├── .github/ │ ├── CODEOWNERS │ ├── dependabot.yml │ └── workflows/ │ ├── lint.yml │ └── test.yml ├── .gitignore ├── .markdownlint.yml ├── .prettierignore ├── .prettierrc ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── LICENSE_APACHE ├── LICENSE_MIT ├── README.md ├── RELEASE_CHECKLIST.md ├── package.json ├── src/ │ ├── index.ts │ ├── mocks.ts │ ├── test/ │ │ ├── getAssetFromKV-optional.ts │ │ ├── getAssetFromKV.ts │ │ ├── mapRequestToAsset.ts │ │ └── serveSinglePageApp.ts │ └── types.ts └── tsconfig.json
SYMBOL INDEX (21 symbols across 4 files)
FILE: src/index.ts
function assignOptions (line 37) | function assignOptions(options?: Partial<Options>): Options {
function serveSinglePageApp (line 75) | function serveSinglePageApp(request: Request, options?: Partial<Options>...
type Evt (line 108) | type Evt = {
FILE: src/mocks.ts
constant HASH (line 3) | const HASH = '123HASHBROWN'
type CacheKey (line 61) | interface CacheKey {
method match (line 68) | async match(key: any) {
method put (line 112) | async put(key: any, val: Response) {
function mockRequestScope (line 133) | function mockRequestScope() {
function mockGlobalScope (line 141) | function mockGlobalScope() {
FILE: src/test/serveSinglePageApp.ts
function testRequest (line 7) | function testRequest(path: string) {
FILE: src/types.ts
type CacheControl (line 1) | type CacheControl = {
type AssetManifestType (line 7) | type AssetManifestType = Record<string, string>
type Options (line 9) | type Options = {
class KVError (line 20) | class KVError extends Error {
method constructor (line 21) | constructor(message?: string, status: number = 500) {
class MethodNotAllowedError (line 30) | class MethodNotAllowedError extends KVError {
method constructor (line 31) | constructor(message: string = `Not a valid request method`, status: nu...
class NotFoundError (line 35) | class NotFoundError extends KVError {
method constructor (line 36) | constructor(message: string = `Not Found`, status: number = 404) {
class InternalError (line 40) | class InternalError extends KVError {
method constructor (line 41) | constructor(message: string = `Internal Error in KV Asset Handler`, st...
Condensed preview — 25 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (93K chars).
[
{
"path": ".editorconfig",
"chars": 94,
"preview": "# https://editorconfig.org\nroot = true\n\n[*]\nend_of_line = lf\nindent_style = tab\ntab_width = 2\n"
},
{
"path": ".gitattributes",
"chars": 25,
"preview": "* text=auto\n* text eol=lf"
},
{
"path": ".github/CODEOWNERS",
"chars": 158,
"preview": "# This is a comment.\n# Each line is a file pattern followed by one or more owners.\n\n*\t@kristianfreeman @rickyrobinett @l"
},
{
"path": ".github/dependabot.yml",
"chars": 106,
"preview": "version: 2\nupdates:\n - package-ecosystem: \"npm\"\n directory: \"/\"\n schedule:\n interval: \"daily\"\n"
},
{
"path": ".github/workflows/lint.yml",
"chars": 553,
"preview": "name: Lint\n\non: [push, pull_request]\n\njobs:\n prettier:\n runs-on: ubuntu-22.04\n steps:\n - uses: actions/check"
},
{
"path": ".github/workflows/test.yml",
"chars": 517,
"preview": "name: Run npm tests\n\non: [push, pull_request]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n "
},
{
"path": ".gitignore",
"chars": 17,
"preview": "node_modules\ndist"
},
{
"path": ".markdownlint.yml",
"chars": 673,
"preview": "# MD001 Header levels should only increment by one level at a time\nMD001: false\n\n# MD004 Unordered list style\nMD004: fal"
},
{
"path": ".prettierignore",
"chars": 53,
"preview": "CHANGELOG.md\npackage.json\npackage-lock.json\ndist/**/*"
},
{
"path": ".prettierrc",
"chars": 123,
"preview": "{\n\t\"endOfLine\": \"lf\",\n\t\"trailingComma\": \"all\",\n\t\"singleQuote\": true,\n\t\"useTabs\": true,\n\t\"semi\": false,\n\t\"printWidth\": 10"
},
{
"path": "CHANGELOG.md",
"chars": 25709,
"preview": "# Changelog\n\n## 0.3.1\n\n- ## Maintenance\n\n - **Remove tests from npm package to reduce npm package size - [boidolr], [pu"
},
{
"path": "CODE_OF_CONDUCT.md",
"chars": 5264,
"preview": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participa"
},
{
"path": "LICENSE_APACHE",
"chars": 9722,
"preview": " Apache License\n Version 2.0, January 2004\n http"
},
{
"path": "LICENSE_MIT",
"chars": 1086,
"preview": "Copyright (c) 2018 Ashley Williams <ashley666ashley@gmail.com>\n\nPermission is hereby granted, free of charge, to any\nper"
},
{
"path": "README.md",
"chars": 194,
"preview": "This repository has been archived and `@cloudflare/kv-asset-handler` has moved to [`workers-sdk`](https://github.com/clo"
},
{
"path": "RELEASE_CHECKLIST.md",
"chars": 3209,
"preview": "# Release Checklist\n\nThis is a list of the things that need to happen during a release.\n\n## Build a Release\n\n### Prepare"
},
{
"path": "package.json",
"chars": 1309,
"preview": "{\n\t\"name\": \"@cloudflare/kv-asset-handler\",\n\t\"version\": \"0.3.1\",\n\t\"description\": \"Routes requests to KV assets\",\n\t\"main\":"
},
{
"path": "src/index.ts",
"chars": 10979,
"preview": "import * as mime from 'mime'\nimport {\n\tOptions,\n\tCacheControl,\n\tMethodNotAllowedError,\n\tNotFoundError,\n\tInternalError,\n\t"
},
{
"path": "src/mocks.ts",
"chars": 4956,
"preview": "const makeServiceWorkerEnv = require('service-worker-mock')\n\nconst HASH = '123HASHBROWN'\n\nexport const getEvent = (reque"
},
{
"path": "src/test/getAssetFromKV-optional.ts",
"chars": 838,
"preview": "import test from 'ava'\nimport { mockRequestScope, mockGlobalScope, getEvent, sleep, mockKV, mockManifest } from '../mock"
},
{
"path": "src/test/getAssetFromKV.ts",
"chars": 17290,
"preview": "import test from 'ava'\nimport { mockRequestScope, mockGlobalScope, getEvent, sleep, mockKV, mockManifest } from '../mock"
},
{
"path": "src/test/mapRequestToAsset.ts",
"chars": 1332,
"preview": "import test from 'ava'\nimport { mockRequestScope, mockGlobalScope } from '../mocks'\nmockGlobalScope()\n\nimport { mapReque"
},
{
"path": "src/test/serveSinglePageApp.ts",
"chars": 1270,
"preview": "import test from 'ava'\nimport { mockRequestScope, mockGlobalScope } from '../mocks'\nmockGlobalScope()\n\nimport { serveSin"
},
{
"path": "src/types.ts",
"chars": 1355,
"preview": "export type CacheControl = {\n\tbrowserTTL: number\n\tedgeTTL: number\n\tbypassCache: boolean\n}\n\nexport type AssetManifestType"
},
{
"path": "tsconfig.json",
"chars": 354,
"preview": "{\n\t\"compilerOptions\": {\n\t\t\"outDir\": \"./dist\",\n\t\t\"noImplicitAny\": true,\n\t\t\"target\": \"ES2017\",\n\t\t\"allowJs\": false,\n\t\t\"lib\""
}
]
About this extraction
This page contains the full source code of the cloudflare/kv-asset-handler GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 25 files (85.1 KB), approximately 23.0k tokens, and a symbol index with 21 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.