From be04f0bdade71112032c26fb1b0b288240fc7212 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 18:05:05 -0700 Subject: [PATCH 1/5] Rename Mounts section of server.md to Web Packages --- book/src/server.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/book/src/server.md b/book/src/server.md index 50c1e947..9b70aed4 100644 --- a/book/src/server.md +++ b/book/src/server.md @@ -226,8 +226,11 @@ fingerprint and revision. If a file uploaded with `filepack upload --file` is not reachable from any package head, it will be deleted by the next run of `filepack gc`. -Mounts ------- +Web Packages +------------ + +Arbitrary web content can be hosted by the Filepack server using mounted web +packages. Web packages contain web content with a `static/index.html` entry point. They are [currently unstable](unstable-features.md) and will be rejected for upload From 0c9da5cf34cc3bde8b5fb39a52967c8ebe66e586 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 18:19:29 -0700 Subject: [PATCH 2/5] Add Signing Packages section --- book/src/quickstart.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/src/quickstart.md b/book/src/quickstart.md index 1292d1e3..47a28d32 100644 --- a/book/src/quickstart.md +++ b/book/src/quickstart.md @@ -108,7 +108,8 @@ filepack verify --fingerprint As long as the fingerprint has not been modified, any change to the package will cause `filepack` to exit with a non-zero exit code. -Finally, packages can be verified by signature. +Signing Packages +---------------- Generate a new key pair with the default name `master`: @@ -135,7 +136,7 @@ filepack verify --key ``` Any change to the package will cause `filepack` to exit with a non-zero exit -code, and as long as your private key is secure, nobody can create a signature +code. As long as your private key is secure, nobody can create a signature which verifies against your public key. Sharing Packages From c355eb576843069b45051dbf21f7b58a7a6b6f6d Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 18:37:56 -0700 Subject: [PATCH 3/5] Deduplicate Response Body header --- crates/generate/templates/route.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/crates/generate/templates/route.md b/crates/generate/templates/route.md index 749765c9..8cfff4c1 100644 --- a/crates/generate/templates/route.md +++ b/crates/generate/templates/route.md @@ -64,37 +64,25 @@ An arbitrary byte string. %% } %% } %% if let Some(response) = &endpoint.response { -%% match response { -%% Response::Deco { fields } => { ### Response Body +%% match response { +%% Response::Deco { fields } => { A deco-encoded struct: {{ DecoFieldsMd { fields, registry: self.registry } }} %% } %% Response::File => { - -### Response Body - The contents of a file. %% } %% Response::Html => { - -### Response Body - An HTML page. %% } %% Response::Redirect => { - -### Response Body - A redirect. %% } %% Response::Static => { - -### Response Body - A static asset. %% } %% } From ad6d5a3c1438ab6776ed6d9c61ecf7cf568e64bd Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 19:01:24 -0700 Subject: [PATCH 4/5] Document upload API --- book/src/server.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/book/src/server.md b/book/src/server.md index 9b70aed4..2970103b 100644 --- a/book/src/server.md +++ b/book/src/server.md @@ -191,6 +191,27 @@ If the current package head differs from the recorded head in `filepack upload` will abort. If two clients race to update the same package, the server will accept the first and reject the second with `409 Conflict`. +### Upload API + +Package uploads are content-addressed and bottom up. + +Files, directories, and revisions are uploaded using [`PUT +/api/file/{hash}`](routes/api-file-hash.md#put). + +Directories are verified using [`POST +/api/directory/{hash}`](routes/api-directory-hash.md#post), which requires that +all files have been uploaded and all subdirectories have been verified. + +The package is verified using [`POST +/api/package/{fingerprint}`](routes/api-package-fingerprint.md#post), which +requires that the package root directory has already been verified and package +metadata is valid. + +Finally, the revision is verified and the package number obtained using [`POST +/api/revision/{revision}`](routes/api-revision-revision.md#post), which +requires that the package has been verified and the revision has been uploaded +and is valid. + Downloading Packages -------------------- From b54db0bc4ee2faca04bfa64cb441644e5642c926 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 19:11:04 -0700 Subject: [PATCH 5/5] Modify --- book/src/server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/server.md b/book/src/server.md index 2970103b..a1b94b49 100644 --- a/book/src/server.md +++ b/book/src/server.md @@ -250,7 +250,7 @@ package head, it will be deleted by the next run of `filepack gc`. Web Packages ------------ -Arbitrary web content can be hosted by the Filepack server using mounted web +Arbitrary web content can be hosted on a Filepack server using mounted web packages. Web packages contain web content with a `static/index.html` entry point. They