https://github.com/stevelr/kv-assets

Store static assets in Workers KV for Rust-WASM Worker HTTP servers
https://github.com/stevelr/kv-assets

static-site wasm wasm-service workers-kv

Last synced: about 1 month ago
JSON representation

Store static assets in Workers KV for Rust-WASM Worker HTTP servers

• Host: GitHub
• URL: https://github.com/stevelr/kv-assets
• Owner: stevelr
• License: apache-2.0
• Created: 2021-01-17T23:52:53.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2021-03-06T16:39:50.000Z (almost 4 years ago)
• Last Synced: 2024-11-14T20:12:55.239Z (about 2 months ago)
• Topics: static-site, wasm, wasm-service, workers-kv
• Language: Rust
• Homepage:
• Size: 16.6 KB
• Stars: 2
• Watchers: 1
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE-APACHE

Awesome Lists containing this project

README

        
# kv-assets & kv-sync

Store static assets in Workers KV for Rust-WASM Worker HTTP servers

The command-line program `kv-sync`, is a build tool that syncs

files between a local folder and Workers KV,

and generates a small manifest that is published with the worker wasm.

This crate was originally developed to support `StaticFileHandler` from

[`wasm-service`](https://github.com/stevelr/wasm-service),

to add static file support for Rust Worker-based http servers.

Although `wrangler` does a similar kind of sync for projects 

configured as a Workers "Site", 

(and we do reuse a lot of code from `wrangler` in this implementation),

there are a few differences:

- this works with Rust projects

  

- The generated manifest is bincode-serialized to a local file, and

  compiled into the wasm package as a static byte array using,

  for example, `include_bytes!("../data/assets.bin")`.

  

- Whereas a wrangler site manifest contains just the KV key path,

  this manifest contains additional metadata such as last modified time

  (from the file system), which can be used to process the HTTP header

  "If-Modified-Since", so the worker can decide

  whether to return 304-Not-Modified without needing to access KV.

  

## Installation

To install kv-sync, `cargo install kv-assets`, and the program `kv-sync`

will be added to `.cargo/bin`. 

If you want to include the kv-assets library in your project, add a line

to Cargo.toml:

    `kv-assets = "0.2"`

## `kv-sync` operations

`kv-sync` does the following:

- Generates `AssetIndex` of all files in the specified directory,

  (default `./public`), skipping files beginning with "." 

  or mentioned in .gitignore or .ignore

  (the search path for .gitignore and .ignore includes the asset folder

  and its parent)

  `AssetIndex` is a `HashMap`, where

  the key is the relative path from the top asset folder.

  The `AssetIndex` is serialized with 

  [`bincode`](https://crates.io/crates/bincode) into a local file.

  

- Uploads new and updated files to KV storage, using a KV key

  that includes a file checksum to act as a unique version id.

  

- If you run `kv-sync --prune`, it will prune KV storage

  by removing obsolete files (previous versions no longer referenced).

  Don't use this flag until the code (with the updated assets.bin) 

  has been successively published, though, or else your'll get file not found errors.

  

  

## Adding `kv-sync` to dev workflow

Run `kv-sync` at least once before publishing the worker the first time.

This will upload the files _and_ generate the manifest.

It is not necessary to run `kv-sync` again until there is a change

to assets (anything in the `public` folder). 

If a file in that folder changes, run the following:

```sh

kv-sync

wrangler publish

# if wrangler publish succeeded without errors, then also run

kv-sync --prune

```

The first kv-sync regnerates the manifest and uploads modified files;

and wrangler publish publishes the code with the updated manifest.

if publish succeeds, it is safe

to run the prune step to remove old assets in KV storage.