Hare/wip-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: Hare/wip-rs:work/T-13-operation-outcome
Branches Tags
Hare/wip-rs:master Hare/wip-rs:work/T-28-text-view-tokens Hare/wip-rs:work/T-27-text-view Hare/wip-rs:work/T-23-scoped-consumers Hare/wip-rs:work/T-22-scope-lifetimes Hare/wip-rs:work/T-21-scope-object-lifetime Hare/wip-rs:work/T-24-canonical-text-view Hare/wip-rs:work/T-20-structured-interface-references Hare/wip-rs:work/T-19-extensible-filesystem Hare/wip-rs:work/T-18-remove-retrieval-batch Hare/wip-rs:work/T-16-http-failure-boundaries Hare/wip-rs:work/T-17-wip-http Hare/wip-rs:work/T-9-interactive-wip-tui Hare/wip-rs:work/T-11-stateful-client-runtime Hare/wip-rs:work/T-10-fs-server Hare/wip-rs:work/T-15-canonical-https-semantics Hare/wip-rs:work/T-14-https-binding Hare/wip-rs:work/T-13-operation-outcome Hare/wip-rs:work/T-12-protocol-errors Hare/wip-rs:work/T-6-restore-virtual-workspace Hare/wip-rs:work/T-8-host-path-semantics Hare/wip-rs:work/T-5-canonical-interface-semantics Hare/wip-rs:work/T-7-canonical-protocol-model Hare/wip-rs:work/T-4-end-to-end-public-api Hare/wip-rs:work/T-2-host-publication Hare/wip-rs:work/T-1-interface-authoring Hare/wip-rs:work/T-3-wip-protocol
Hare/wip-rs:v0.2.0 Hare/wip-rs:v0.1.0
..
pull from: Hare/wip-rs:work/T-10-fs-server
Branches Tags
Hare/wip-rs:master Hare/wip-rs:work/T-28-text-view-tokens Hare/wip-rs:work/T-27-text-view Hare/wip-rs:work/T-23-scoped-consumers Hare/wip-rs:work/T-22-scope-lifetimes Hare/wip-rs:work/T-21-scope-object-lifetime Hare/wip-rs:work/T-24-canonical-text-view Hare/wip-rs:work/T-20-structured-interface-references Hare/wip-rs:work/T-19-extensible-filesystem Hare/wip-rs:work/T-18-remove-retrieval-batch Hare/wip-rs:work/T-16-http-failure-boundaries Hare/wip-rs:work/T-17-wip-http Hare/wip-rs:work/T-9-interactive-wip-tui Hare/wip-rs:work/T-11-stateful-client-runtime Hare/wip-rs:work/T-10-fs-server Hare/wip-rs:work/T-15-canonical-https-semantics Hare/wip-rs:work/T-14-https-binding Hare/wip-rs:work/T-13-operation-outcome Hare/wip-rs:work/T-12-protocol-errors Hare/wip-rs:work/T-6-restore-virtual-workspace Hare/wip-rs:work/T-8-host-path-semantics Hare/wip-rs:work/T-5-canonical-interface-semantics Hare/wip-rs:work/T-7-canonical-protocol-model Hare/wip-rs:work/T-4-end-to-end-public-api Hare/wip-rs:work/T-2-host-publication Hare/wip-rs:work/T-1-interface-authoring Hare/wip-rs:work/T-3-wip-protocol
Hare/wip-rs:v0.2.0 Hare/wip-rs:v0.1.0
8 Commits
work/T-13-operation-outcome .. work/T-10-fs-server
Author SHA1 Message Date
Hare 780150d7ae fix: bound HTTP intake and response lifetimes 2026-09-30 09:23:12 +09:00
Hare f5034c0e4b fix: bound filesystem execution and preserve guarantees 2026-09-30 09:09:09 +09:00
Hare df51da3d03 feat: add bounded filesystem projection server 2026-09-30 08:53:44 +09:00
Hare fdfaa3a685 feat(host): decode operation arguments in dispatch boundary 2026-09-30 08:53:43 +09:00
Hare 96db3dd6a8 fix: honor Accept media parameters 2026-09-30 07:59:50 +09:00
Hare 625f4c148d fix(https): align canonical binding semantics 2026-09-30 07:50:51 +09:00
Hare beeffae9c5 fix: validate HTTPS binding limits and response ordering 2026-09-30 06:43:02 +09:00
Hare 56923c1160 feat: implement WIP over HTTPS v1 binding 2026-09-30 06:32:04 +09:00
24 changed files with 8224 additions and 37 deletions
Expand all files Collapse all files
Cargo.lock
Generated
+415
View File
@@ -2,12 +2,83 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "base64"
version = "0.22.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
[[package]]
name = "bitflags"
version = "2.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
[[package]]
name = "bytes"
version = "1.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
[[package]]
name = "cfg-if"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
[[package]]
name = "displaydoc"
version = "0.2.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "equivalent"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
[[package]]
name = "errno"
version = "0.3.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
"windows-sys",
]
[[package]]
name = "fastrand"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
[[package]]
name = "form_urlencoded"
version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
dependencies = [
"percent-encoding",
]
[[package]]
name = "getrandom"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
"libc",
"r-efi",
]
[[package]]
name = "glob"
version = "0.3.4"
@@ -20,6 +91,120 @@ version = "0.17.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
[[package]]
name = "http"
version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
dependencies = [
"bytes",
"itoa",
]
[[package]]
name = "icu_collections"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"
dependencies = [
"displaydoc",
"potential_utf",
"utf8_iter",
"yoke",
"zerofrom",
"zerovec",
]
[[package]]
name = "icu_locale_core"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"
dependencies = [
"displaydoc",
"litemap",
"tinystr",
"writeable",
"zerovec",
]
[[package]]
name = "icu_normalizer"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"
dependencies = [
"icu_collections",
"icu_normalizer_data",
"icu_properties",
"icu_provider",
"smallvec",
"zerovec",
]
[[package]]
name = "icu_normalizer_data"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"
[[package]]
name = "icu_properties"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"
dependencies = [
"displaydoc",
"icu_collections",
"icu_locale_core",
"icu_properties_data",
"icu_provider",
"zerotrie",
"zerovec",
]
[[package]]
name = "icu_properties_data"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"
[[package]]
name = "icu_provider"
version = "2.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"
dependencies = [
"displaydoc",
"icu_locale_core",
"writeable",
"yoke",
"zerofrom",
"zerotrie",
"zerovec",
]
[[package]]
name = "idna"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
dependencies = [
"idna_adapter",
"smallvec",
"utf8_iter",
]
[[package]]
name = "idna_adapter"
version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
dependencies = [
"icu_normalizer",
"icu_properties",
]
[[package]]
name = "indexmap"
version = "2.14.2"
@@ -36,12 +221,51 @@ version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "libc"
version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
[[package]]
name = "linux-raw-sys"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "litemap"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "percent-encoding"
version = "2.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
[[package]]
name = "potential_utf"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
dependencies = [
"zerovec",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
@@ -60,6 +284,25 @@ dependencies = [
"proc-macro2",
]
[[package]]
name = "r-efi"
version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
[[package]]
name = "rustix"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"
dependencies = [
"bitflags",
"errno",
"libc",
"linux-raw-sys",
"windows-sys",
]
[[package]]
name = "serde"
version = "1.0.229"
@@ -111,6 +354,18 @@ dependencies = [
"serde_core",
]
[[package]]
name = "smallvec"
version = "1.16.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e"
[[package]]
name = "stable_deref_trait"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
[[package]]
name = "syn"
version = "2.0.119"
@@ -133,12 +388,36 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "synstructure"
version = "0.14.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "target-tuple"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "876fef147edbcbddc8ac5cbbba92c7b86519e314e86638596c09673b2ed01e7f"
[[package]]
name = "tempfile"
version = "3.27.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
dependencies = [
"fastrand",
"getrandom",
"once_cell",
"rustix",
"windows-sys",
]
[[package]]
name = "termcolor"
version = "1.4.1"
@@ -148,6 +427,16 @@ dependencies = [
"winapi-util",
]
[[package]]
name = "tinystr"
version = "0.8.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"
dependencies = [
"displaydoc",
"zerovec",
]
[[package]]
name = "toml"
version = "1.1.6+spec-1.1.0"
@@ -208,6 +497,24 @@ version = "1.0.26"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
[[package]]
name = "url"
version = "2.5.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
dependencies = [
"form_urlencoded",
"idna",
"percent-encoding",
"serde",
]
[[package]]
name = "utf8_iter"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "winapi-util"
version = "0.1.11"
@@ -238,6 +545,19 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
[[package]]
name = "wip-fs-server"
version = "0.1.0"
dependencies = [
"http",
"rustix",
"tempfile",
"wip-host",
"wip-https",
"wip-interface",
"wip-protocol",
]
[[package]]
name = "wip-host"
version = "0.1.0"
@@ -247,6 +567,18 @@ dependencies = [
"wip-protocol",
]
[[package]]
name = "wip-https"
version = "0.1.0"
dependencies = [
"base64",
"http",
"serde",
"serde_json",
"url",
"wip-protocol",
]
[[package]]
name = "wip-interface"
version = "0.1.0"
@@ -278,6 +610,89 @@ dependencies = [
"wip-protocol",
]
[[package]]
name = "writeable"
version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
[[package]]
name = "yoke"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
dependencies = [
"stable_deref_trait",
"yoke-derive",
"zerofrom",
]
[[package]]
name = "yoke-derive"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
"synstructure",
]
[[package]]
name = "zerofrom"
version = "0.1.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
dependencies = [
"zerofrom-derive",
]
[[package]]
name = "zerofrom-derive"
version = "0.1.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
"synstructure",
]
[[package]]
name = "zerotrie"
version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
dependencies = [
"displaydoc",
"yoke",
"zerofrom",
]
[[package]]
name = "zerovec"
version = "0.11.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"
dependencies = [
"yoke",
"zerofrom",
"zerovec-derive",
]
[[package]]
name = "zerovec-derive"
version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "zmij"
version = "1.0.23"
README.md
+29 -9
View File
@@ -3,17 +3,24 @@
Rust building blocks for the Web Interface Protocol (WIP).
The repository is a resolver-3 virtual Cargo workspace whose packages all live
under `crates/*`. It provides a transport-independent protocol model, a Rust
interface-authoring facade, a request-scoped host runtime, and a private
public-API conformance consumer. The repository root is not itself a package.
HTTP and other transport bindings are intentionally outside the supported
slice.
under `crates/*`. It provides a transport-independent protocol model, the
standard framework-independent WIP over HTTPS v1 binding, a Rust
interface-authoring facade, a request-scoped host runtime, a bounded Linux
filesystem projection server, and a private public-API conformance consumer. The
repository root is not itself a package.
## Crate graph and responsibilities
```text
wip-fs-server (request-time filesystem projection and loopback listener)
├── wip-https standard routes/codecs/envelopes/batching
├── wip-host request-scoped publication and dispatch
└── wip-interface macro-generated filesystem capabilities
wip-public-api-example (workspace-only executable, integration tests, doctest)
├── wip-protocol logical declarations, values, calls, and validation
├── wip-https standard HTTPS v1 routes, JSON codecs, envelopes, and batching
│ └── wip-protocol
├── wip-interface application DTO codecs and interface authoring facade
│ ├── wip-protocol
│ └── wip-interface-macros proc-macro implementation detail
@@ -25,15 +32,17 @@ wip-public-api-example (workspace-only executable, integration tests, doctest)
| Crate | Responsibility | Does not own |
| --- | --- | --- |
| `wip-protocol` | Transport-independent descriptors, object/call/result types, logical `Value`s, validation, and stable protocol error categories. | Application DTOs, implementations, persistence, or wire encoding. |
| `wip-https` | Standard HTTPS v1 endpoint/route derivation, UTF-8 JSON codecs, direct success bodies, error/status classification, and retrieval batches. | HTTP I/O, TLS termination, authentication schemes, server frameworks, filesystem projection, or client presentation/cache policy. |
| `wip-interface` | The public `WipType`/`interface` authoring API, Rust-to-protocol codecs, generated descriptors, and typed implementation dispatch. | Object publication, backend lifetime, or transport policy. |
| `wip-interface-macros` | Procedural-macro expansion used by `wip-interface`. It is not an application dependency. | A supported direct user API. |
| `wip-host` | Opaque interface registration, explicit object membership, validator checks, and interface-qualified dispatch against one host-owned instance. | Backend atomicity, global object lookup, or network serving. |
| `wip-public-api-example` | An independently compiled consumer of only the three public crates. Its DTOs and traits are application-owned; its implementation and backend handle remain host-private. | Reusable library API or a production server. |
| `wip-host` | Opaque interface registration, explicit object membership, validator checks, interface-qualified dispatch against one host-owned instance, and descriptor-guided argument decoding inside that same resolution boundary. | Backend atomicity, global object lookup, or network serving. |
| `wip-fs-server` | Linux directory-handle-confined request-time projection, bounded BFS trees and file operations, standard `wip-https` dispatch/batch handling, and a loopback HTTP binary for TLS-proxy or explicit development use. | A new wire profile, implicit symlink following, non-loopback cleartext, authentication policy, or filesystem-wide preregistration. |
| `wip-public-api-example` | An independently compiled consumer of the protocol, authoring, and host public crates. Its DTOs and traits are application-owned; its implementation and backend handle remain host-private. | Reusable library API or a production server. |
The boundary is intentional: protocol types describe what can cross a
transport; application DTOs opt into that model with `WipType`; a host-private
implementation owns credentials, handles, and backend state; and a future
transport maps its own routes/envelopes to `CallOperationRequest` and
implementation owns credentials, handles, and backend state; and `wip-https`
maps standard routes/envelopes to `CallOperationRequest` and
`CallOperationResponse` without placing transport-specific types in descriptors
or application traits.
@@ -236,6 +245,17 @@ rolled back. Without that proof, post-invocation failures remain
comparison and backend commit atomic and return a validator describing the state
that becomes committed.
## Filesystem projection server
[`crates/wip-fs-server`](crates/wip-fs-server) contains the practical server
binary and its full security model, configuration, curl walkthrough, and
resource/failure semantics. It resolves every object from current filesystem
state, uses pinned directory-relative handles without following symlinks, omits
non-UTF-8 backend names, performs bounded breadth-first tree discovery, and
publishes validator-protected replacement only in explicit read-write mode.
The built-in cleartext listener is loopback-only: production HTTPS is explicitly
delegated to a reverse proxy, while local plain HTTP requires an opt-in flag.
## Validation
Enter the dev shell and run the acceptance commands exactly:
crates/wip-fs-server/Cargo.toml
+19
View File
@@ -0,0 +1,19 @@
[package]
name = "wip-fs-server"
version = "0.1.0"
edition = "2024"
description = "Request-time filesystem projection server for WIP over HTTPS"
license = "MIT OR Apache-2.0"
readme = "README.md"
publish = false
[dependencies]
http = "1"
rustix = { version = "1.1", features = ["fs"] }
wip-host = { path = "../wip-host" }
wip-https = { path = "../wip-https" }
wip-interface = { path = "../wip-interface" }
wip-protocol = { path = "../wip-protocol" }
[dev-dependencies]
tempfile = "3"
crates/wip-fs-server/README.md
+148
View File
@@ -0,0 +1,148 @@
# wip-fs-server
`wip-fs-server` projects one configured Linux filesystem directory onto WIP
Worldspace `/` at request time. It does not register the filesystem contents or
keep one object instance per entry. It uses `wip-host` for publication and typed
operation dispatch and uses the standard `wip-https` routes, JSON codecs,
envelopes, batching, and HTTP status mapping.
## Security model
- The effective root is opened once as a directory capability. Root path
components must be real directories (symlink components are rejected), and the
displayed effective root is read back from that same pinned descriptor. Every
request is resolved segment-by-segment with directory-relative, `O_NOFOLLOW`
handles.
- Symlinks are projected as links and are never followed. Their stored target is
available only through the `SymlinkInspect.read_link` application operation.
- Regular files, directories, symlinks, and unsupported entry types have distinct
public descriptions and capability sets.
- WIP names are Unicode. Linux names that are not valid UTF-8 are deliberately
not published; valid UTF-8 names map byte-for-byte and therefore cannot collide.
Unicode paths containing backend-invalid NUL bytes are likewise treated as
unpublished rather than as backend failures.
- No object `ref` is issued. This avoids claiming representation identity for
hard links or path-specific names. Regular files and symlinks receive an opaque
validator containing filesystem identity plus protected metadata; replacing a
path therefore does not preserve its validator.
- Protocol metadata and errors never contain the backend absolute path. Startup
prints only the explicitly configured effective root and security-sensitive
modes.
- The built-in listener is cleartext and loopback-only. Production deployments
must pass `--behind-tls-proxy` and terminate HTTPS at a trusted reverse proxy.
Plain development HTTP requires the explicit `--development-http` flag.
The implementation currently targets Linux because it uses `O_PATH`,
directory-relative descriptor traversal, and `/proc/self/fd` to reopen the same
pinned backend object without resolving the untrusted Worldspace path twice.
## Run
Read-only behind a TLS-terminating reverse proxy:
```console
cargo run -p wip-fs-server -- \
--root /srv/public-files \
--listen 127.0.0.1:8443 \
--base-path /wip \
--behind-tls-proxy
```
Local development with the write capability deliberately enabled:
```console
cargo run -p wip-fs-server -- \
--root ./example-files \
--listen 127.0.0.1:8080 \
--base-path /wip \
--development-http \
--read-write
```
The server reports the effective root, `ReadOnly`/`ReadWrite` mode, transport
mode, endpoint, and actual listen address. It does not enumerate the root.
## Standard interactions
The following examples use development HTTP for readability. The JSON is the
standard `wip-https` profile; validators and operation `Bytes` are base64 body
fields, never `ETag` or `If-Match` headers.
Fetch root:
```console
curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data '{"path":"/"}'
```
Fetch a bounded tree (the root counts toward `limit`):
```console
curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch_tree \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data '{"path":"/","depth":2,"limit":100}'
```
A regular-file fetch returns the opaque read interface reference and an object
validator. Retrieve that descriptor with:
```console
curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch_interface \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data '{"interface":"<read-interface-from-fetch>"}'
```
Then call a bounded range read:
```console
curl -sS -X POST http://127.0.0.1:8080/wip/v1/call_operation \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data '{
"target":{"path":"/notes.txt","validator":"<base64-validator>"},
"interface":{"reference":"<read-interface>"},
"operation":"read",
"arguments":{"offset":0,"length":4096}
}'
```
In `--read-write` mode a second regular-file interface declares `replace`.
Writes require the current object validator and return the post-write validator:
```console
curl -sS -X POST http://127.0.0.1:8080/wip/v1/call_operation \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
--data '{
"target":{"path":"/notes.txt","validator":"<base64-validator>"},
"interface":{"reference":"<write-interface>"},
"operation":"replace",
"arguments":{"contents":"dXBkYXRlZA=="}
}'
```
`fetch`, `fetch_tree`, and `fetch_interface` can also be combined through the
standard `POST /wip/v1/batch` route. `call_operation` is never batchable.
## Resource and failure behavior
`ResourceLimits` bounds request/response bytes, HTTP request-head bytes, JSON
nesting, batch items, file read/write bytes, tree depth/node count, pinned handles,
and active connections/requests. One absolute request deadline covers header and
body intake, dispatch, cooperative filesystem work, and response transmission;
stalled clients are closed and cannot occupy a worker beyond that bound. Workers
accept connections directly, so the listener never moves more than the configured
concurrency into active userspace service. Advisory file-lock acquisition uses a
nonblocking loop and checks the same deadline/cancellation rather than allowing a
contended lock to stall a worker. Tree traversal is breadth-first and opens only
requested entries. Once a limit or depth boundary is reached it reads only far
enough to
prove whether an additional visible child exists, so `truncated` is true only
when something was actually omitted. I/O failure and cancellation remain errors,
not clean exhaustion.
Whole-file replacement compares the request validator against the identity and
state of the same pinned file handle used for the write. Failures before mutation
carry a `NotCommitted` guarantee and map to `Internal` or
`ResourceLimitExceeded`; a failure after truncation/write begins maps to
`OperationOutcomeUnknown`. The server and Clients do not automatically retry
side-effecting operations.
crates/wip-fs-server/src/interfaces.rs
+43
View File
@@ -0,0 +1,43 @@
//! Filesystem capability interfaces published by the projection.
use wip_interface as wip;
/// Bounded reads from a regular file.
#[wip::interface]
pub trait FileRead {
/// Reads bytes from the current regular file.
///
/// # Returns
/// At most the configured read limit, beginning at `offset`.
fn read(
&self,
/// Byte offset; omitted means zero.
offset: Option<u64>,
/// Requested byte count; omitted means the rest of the file.
length: Option<u64>,
) -> wip::OperationResult<wip::Bytes>;
}
/// Inspection operations for a symbolic link itself.
#[wip::interface]
pub trait SymlinkInspect {
/// Reads the link payload without following it.
///
/// # Returns
/// The platform path bytes stored in the symbolic link.
fn read_link(&self) -> wip::OperationResult<wip::Bytes>;
}
/// Explicitly enabled mutation of a regular file.
#[wip::interface]
pub trait FileWrite {
/// Replaces the current regular file contents through its pinned handle.
///
/// # Returns
/// Unit after the new bytes have been written and synchronized.
fn replace(
&self,
/// Complete replacement contents.
contents: wip::Bytes,
) -> wip::OperationResult<()>;
}
crates/wip-fs-server/src/lib.rs
+191
View File
@@ -0,0 +1,191 @@
//! Request-time filesystem projection served through the standard WIP HTTPS binding.
//!
//! This crate deliberately keeps the boundaries visible:
//!
//! - [`wip_protocol`] owns logical requests and responses;
//! - [`wip_host`] owns object publication, validators, and typed dispatch;
//! - [`wip_https`] owns routes, JSON, envelopes, batching, and status mapping;
//! - this crate owns the filesystem capability boundary and the real HTTP listener.
//!
//! TLS is terminated by an explicitly configured reverse proxy. The built-in
//! listener accepts cleartext only on loopback, either behind that proxy or when
//! [`TransportSecurity::DevelopmentHttp`] is deliberately selected.
#![deny(missing_docs)]
mod interfaces;
mod projection;
mod server;
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::path::PathBuf;
use std::time::Duration;
pub use interfaces::{FileRead, FileWrite, SymlinkInspect};
pub use server::{BoundServer, ServerBuildError, WipFsServer};
/// Filesystem capabilities published by regular files.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AccessMode {
/// Publish bounded reads only.
ReadOnly,
/// Also publish validator-protected whole-file replacement.
ReadWrite,
}
/// How HTTPS is provided for the endpoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransportSecurity {
/// A trusted reverse proxy terminates TLS and forwards to the loopback listener.
ReverseProxyTls,
/// Cleartext HTTP is deliberately enabled for local development only.
DevelopmentHttp,
}
/// Bounded resource policy applied by the HTTP adapter and filesystem provider.
#[derive(Debug, Clone, Copy)]
pub struct ResourceLimits {
/// Standard JSON, body-size, nesting, and batch limits.
pub wire: wip_https::Limits,
/// Maximum bytes returned by one file read.
pub max_file_read_bytes: usize,
/// Maximum bytes accepted by one file replacement.
pub max_file_write_bytes: usize,
/// Maximum accepted `fetch_tree` depth.
pub max_tree_depth: u32,
/// Maximum accepted `fetch_tree` node count, including its root.
pub max_tree_nodes: u32,
/// Maximum simultaneously pinned projected filesystem handles.
pub max_open_handles: usize,
/// Maximum bytes accepted for one HTTP request head, including its terminator.
pub max_http_header_bytes: usize,
/// Maximum requests executing concurrently.
pub max_concurrent_requests: usize,
/// End-to-end deadline for HTTP intake, dispatch, and response transmission.
pub request_timeout: Duration,
}
impl Default for ResourceLimits {
fn default() -> Self {
Self {
wire: wip_https::Limits::new(256 * 1024, 2 * 1024 * 1024, 64, 64)
.expect("default wire limits are nonzero"),
max_file_read_bytes: 1024 * 1024,
max_file_write_bytes: 1024 * 1024,
max_tree_depth: 32,
max_tree_nodes: 1024,
max_open_handles: 2048,
max_http_header_bytes: 16 * 1024,
max_concurrent_requests: 32,
request_timeout: Duration::from_secs(30),
}
}
}
/// Complete listener and projection configuration.
#[derive(Debug, Clone)]
pub struct ServerConfig {
/// Filesystem directory projected as Worldspace `/`.
pub root: PathBuf,
/// Loopback socket used by the built-in cleartext listener.
pub listen: SocketAddr,
/// URL path prefix below which standard `v1/*` routes are mounted.
pub endpoint_base_path: String,
/// Read-only or explicit read-write publication mode.
pub access: AccessMode,
/// TLS termination or explicit development HTTP policy.
pub transport_security: TransportSecurity,
/// Request, operation, traversal, and concurrency bounds.
pub limits: ResourceLimits,
}
impl ServerConfig {
/// Builds a secure-by-default configuration for `root`.
///
/// The listener defaults to an ephemeral loopback port, read-only access,
/// and TLS termination delegated to a reverse proxy.
#[must_use]
pub fn for_root(root: impl Into<PathBuf>) -> Self {
Self {
root: root.into(),
listen: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0),
endpoint_base_path: "/wip".into(),
access: AccessMode::ReadOnly,
transport_security: TransportSecurity::ReverseProxyTls,
limits: ResourceLimits::default(),
}
}
pub(crate) fn validate(&self) -> Result<(), ConfigError> {
if !self.listen.ip().is_loopback() {
return Err(ConfigError::NonLoopbackCleartext);
}
if !valid_base_path(&self.endpoint_base_path) {
return Err(ConfigError::InvalidBasePath);
}
if self.limits.max_file_read_bytes == 0
|| self.limits.max_file_write_bytes == 0
|| self.limits.max_tree_nodes == 0
|| self.limits.max_open_handles == 0
|| self.limits.max_http_header_bytes == 0
|| self.limits.max_concurrent_requests == 0
|| self.limits.request_timeout.is_zero()
{
return Err(ConfigError::ZeroLimit);
}
if self.limits.max_open_handles < self.limits.max_tree_nodes as usize {
return Err(ConfigError::InsufficientHandles);
}
if self.limits.wire.max_response_bytes() < 512 {
return Err(ConfigError::ResponseLimitTooSmall);
}
Ok(())
}
pub(crate) fn endpoint(&self) -> Result<wip_https::Endpoint, ConfigError> {
let endpoint = format!("https://localhost{}", self.endpoint_base_path);
wip_https::Endpoint::parse(&endpoint).map_err(|_| ConfigError::InvalidBasePath)
}
}
/// Invalid server configuration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConfigError {
/// The cleartext built-in listener was exposed beyond loopback.
NonLoopbackCleartext,
/// The endpoint prefix is not an absolute canonical URL path.
InvalidBasePath,
/// A resource limit is zero.
ZeroLimit,
/// Tree nodes could exhaust the configured handle ceiling by construction.
InsufficientHandles,
/// The response limit cannot reliably carry a bounded protocol error envelope.
ResponseLimitTooSmall,
}
impl std::fmt::Display for ConfigError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(match self {
Self::NonLoopbackCleartext => "the built-in cleartext listener must bind to loopback",
Self::InvalidBasePath => {
"endpoint base path must be absolute, canonical, and query-free"
}
Self::ZeroLimit => "all resource limits and the request timeout must be nonzero",
Self::InsufficientHandles => "max_open_handles must cover max_tree_nodes",
Self::ResponseLimitTooSmall => "max_response_bytes must be at least 512",
})
}
}
impl std::error::Error for ConfigError {}
fn valid_base_path(path: &str) -> bool {
path.starts_with('/')
&& !path.contains('?')
&& !path.contains('#')
&& !path.contains("//")
&& !path
.split('/')
.any(|segment| segment == "." || segment == "..")
&& (path == "/" || !path.ends_with('/'))
}
crates/wip-fs-server/src/main.rs
+83
View File
@@ -0,0 +1,83 @@
use std::error::Error;
use std::net::SocketAddr;
use std::path::PathBuf;
use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
fn main() -> Result<(), Box<dyn Error>> {
let mut root: Option<PathBuf> = None;
let mut listen: SocketAddr = "127.0.0.1:8443".parse()?;
let mut base_path = "/wip".to_owned();
let mut access = AccessMode::ReadOnly;
let mut security = None;
let mut arguments = std::env::args().skip(1);
while let Some(argument) = arguments.next() {
match argument.as_str() {
"--root" => root = Some(PathBuf::from(required_value(&mut arguments, "--root")?)),
"--listen" => listen = required_value(&mut arguments, "--listen")?.parse()?,
"--base-path" => base_path = required_value(&mut arguments, "--base-path")?,
"--read-write" => access = AccessMode::ReadWrite,
"--development-http" => {
set_security(&mut security, TransportSecurity::DevelopmentHttp)?
}
"--behind-tls-proxy" => {
set_security(&mut security, TransportSecurity::ReverseProxyTls)?
}
"--help" | "-h" => {
print_help();
return Ok(());
}
unknown => return Err(format!("unknown argument `{unknown}`; use --help").into()),
}
}
let root = root.ok_or("--root is required")?;
let transport_security =
security.ok_or("select exactly one of --behind-tls-proxy or --development-http")?;
let mut config = ServerConfig::for_root(root);
config.listen = listen;
config.endpoint_base_path = base_path;
config.access = access;
config.transport_security = transport_security;
let server = WipFsServer::new(config)?;
let effective_root = server.effective_root().to_owned();
let endpoint = server.endpoint().clone();
let bound = server.bind()?;
eprintln!(
"wip-fs-server root={} access={access:?} transport={transport_security:?} endpoint={} listen={}",
effective_root.display(),
endpoint,
bound.local_addr()
);
bound.serve()?;
Ok(())
}
fn required_value(
arguments: &mut impl Iterator<Item = String>,
option: &str,
) -> Result<String, Box<dyn Error>> {
arguments
.next()
.ok_or_else(|| format!("{option} requires a value").into())
}
fn set_security(
security: &mut Option<TransportSecurity>,
value: TransportSecurity,
) -> Result<(), Box<dyn Error>> {
if security.replace(value).is_some() {
Err("select only one transport-security mode".into())
} else {
Ok(())
}
}
fn print_help() {
println!(
"Usage: wip-fs-server --root PATH [--listen 127.0.0.1:8443] \\\n [--base-path /wip] [--read-write] \\\n (--behind-tls-proxy | --development-http)\n\n\
The built-in listener is cleartext and loopback-only. In production, \
select --behind-tls-proxy and terminate HTTPS at a trusted reverse proxy."
);
}
crates/wip-fs-server/src/projection.rs
+1162
View File
File diff suppressed because it is too large Load Diff
crates/wip-fs-server/src/server.rs
+747
View File
@@ -0,0 +1,747 @@
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpListener, TcpStream};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread;
use std::time::{Duration, Instant};
use http::{Request, Response, StatusCode};
use wip_host::{ExecutionContext, ObjectProvider};
use wip_https::{
BatchRequestKind, BatchResponse, BatchResponseItem, BatchSuccess, CodecError, EncodeHttpError,
Endpoint, RequestMetadataError, ResourceLimitKind, Route, decode_batch_request,
decode_call_operation_metadata, decode_fetch_interface_request, decode_fetch_request,
decode_fetch_tree_request, encode_batch_error_response,
encode_batch_resource_limit_error_response, encode_batch_response,
encode_call_operation_response, encode_fetch_interface_response, encode_fetch_response,
encode_fetch_tree_response, encode_protocol_error_response,
encode_resource_limit_error_response, validate_http_request,
};
use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
use crate::projection::Projection;
use crate::{ConfigError, ServerConfig};
/// Filesystem projection and framework-neutral standard WIP request adapter.
pub struct WipFsServer {
config: ServerConfig,
endpoint: Endpoint,
effective_root: std::path::PathBuf,
projection: Arc<Projection>,
}
impl WipFsServer {
/// Validates configuration and opens the configured directory capability.
pub fn new(config: ServerConfig) -> Result<Self, ServerBuildError> {
config.validate()?;
let endpoint = config.endpoint()?;
let projection = Projection::open(&config.root, config.access, config.limits)?;
let effective_root = projection.effective_root()?;
Ok(Self {
config,
endpoint,
effective_root,
projection: Arc::new(projection),
})
}
/// Returns the canonical effective filesystem root opened by the server.
#[must_use]
pub fn effective_root(&self) -> &std::path::Path {
&self.effective_root
}
/// Returns the configured transport endpoint prefix.
#[must_use]
pub fn endpoint(&self) -> &Endpoint {
&self.endpoint
}
/// Handles one already-buffered HTTP request with the standard `wip-https` codecs.
///
/// Listener integrations must enforce the same body limit while collecting bytes.
#[must_use]
pub fn handle_http(&self, request: Request<Vec<u8>>) -> Response<Vec<u8>> {
self.handle_http_with_deadline(request, Instant::now() + self.config.limits.request_timeout)
}
fn handle_http_with_deadline(
&self,
request: Request<Vec<u8>>,
deadline: Instant,
) -> Response<Vec<u8>> {
let Some(route) = self.route(request.uri().path()) else {
return empty_response(StatusCode::NOT_FOUND);
};
if let Err(error) = validate_http_request(&self.endpoint, route, &request) {
return self.metadata_error(route, error);
}
let context = ExecutionContext::new()
.with_deadline(deadline)
.with_resource_budget(u64::from(self.config.limits.max_tree_nodes));
match route {
Route::Fetch => self.fetch(request.body(), &context),
Route::FetchTree => self.fetch_tree(request.body(), &context),
Route::FetchInterface => self.fetch_interface(request.body()),
Route::CallOperation => self.call_operation(request.body(), &context),
Route::Batch => self.batch(request.body(), &context),
}
}
/// Binds the built-in bounded loopback HTTP listener.
///
/// The listener is cleartext by design. Configuration must explicitly state
/// whether TLS is terminated by a reverse proxy or development HTTP is in use.
pub fn bind(self) -> Result<BoundServer, ServerBuildError> {
let listener = TcpListener::bind(self.config.listen)
.map_err(|error| ServerBuildError::Listener(error.to_string()))?;
listener
.set_nonblocking(true)
.map_err(|error| ServerBuildError::Listener(error.to_string()))?;
let local_addr = listener
.local_addr()
.map_err(|error| ServerBuildError::Listener(error.to_string()))?;
Ok(BoundServer {
local_addr,
service: Arc::new(self),
listener: Arc::new(listener),
})
}
fn route(&self, path: &str) -> Option<Route> {
[
Route::Fetch,
Route::FetchTree,
Route::FetchInterface,
Route::CallOperation,
Route::Batch,
]
.into_iter()
.find(|route| self.endpoint.route(*route).path() == path)
}
fn fetch(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
let request = match decode_fetch_request(body, self.config.limits.wire) {
Ok(request) => request,
Err(error) => return self.codec_error(ProtocolInteraction::Fetch, error),
};
match self
.projection
.fetch_with_context(context, &request.path)
.map_err(|error| error.protocol_error())
{
Ok(object) => encode_fetch_response(&request, &object, self.config.limits.wire)
.unwrap_or_else(|error| self.read_encode_error(ProtocolInteraction::Fetch, error)),
Err(error) => self.protocol_error(ProtocolInteraction::Fetch, &error, None),
}
}
fn fetch_tree(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
let request = match decode_fetch_tree_request(body, self.config.limits.wire) {
Ok(request) => request,
Err(error) => return self.codec_error(ProtocolInteraction::FetchTree, error),
};
match self.projection.fetch_tree(context, &request) {
Ok(tree) => encode_fetch_tree_response(&request, &tree, self.config.limits.wire)
.unwrap_or_else(|error| {
self.read_encode_error(ProtocolInteraction::FetchTree, error)
}),
Err(error) => self.protocol_error(ProtocolInteraction::FetchTree, &error, None),
}
}
fn fetch_interface(&self, body: &[u8]) -> Response<Vec<u8>> {
let request = match decode_fetch_interface_request(body, self.config.limits.wire) {
Ok(request) => request,
Err(error) => return self.codec_error(ProtocolInteraction::FetchInterface, error),
};
match self.projection.fetch_interface(&request) {
Ok(interface) => {
encode_fetch_interface_response(&request, &interface, self.config.limits.wire)
.unwrap_or_else(|error| {
self.read_encode_error(ProtocolInteraction::FetchInterface, error)
})
}
Err(error) => self.protocol_error(ProtocolInteraction::FetchInterface, &error, None),
}
}
fn call_operation(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
let metadata = match decode_call_operation_metadata(body, self.config.limits.wire) {
Ok(metadata) => metadata,
Err(error) => return self.codec_error(ProtocolInteraction::CallOperation, error),
};
let may_commit = metadata.operation == "replace";
let decoded = std::sync::Mutex::new(None);
let execution = self.projection.call_operation_with_context_and_decoder(
context,
metadata.target.clone(),
metadata.interface.clone(),
metadata.operation.clone(),
|descriptor| {
let request = metadata.decode_request(body, descriptor, self.config.limits.wire)?;
let arguments = request.arguments.clone();
*decoded.lock().unwrap_or_else(|error| error.into_inner()) =
Some((request, descriptor.clone()));
Ok::<_, CodecError>(arguments)
},
);
match execution.map_err(|error| error.protocol_error()) {
Ok(result) => {
let Some((request, descriptor)) = decoded
.into_inner()
.unwrap_or_else(|error| error.into_inner())
else {
let error = ProtocolError {
code: if may_commit {
ProtocolErrorCode::OperationOutcomeUnknown
} else {
ProtocolErrorCode::Internal
},
message: "operation completed without response metadata".into(),
};
return self.protocol_error(ProtocolInteraction::CallOperation, &error, None);
};
encode_call_operation_response(
&request,
&descriptor,
&result,
self.config.limits.wire,
)
.unwrap_or_else(|encode_error| {
if !may_commit {
return self
.read_encode_error(ProtocolInteraction::CallOperation, encode_error);
}
// Replacement may already be committed, so a response
// encoding failure cannot carry a non-commit guarantee.
let error = ProtocolError {
code: ProtocolErrorCode::OperationOutcomeUnknown,
message: "operation completed but its response could not be encoded".into(),
};
self.protocol_error(ProtocolInteraction::CallOperation, &error, None)
})
}
Err(error) => self.protocol_error(ProtocolInteraction::CallOperation, &error, None),
}
}
fn batch(&self, body: &[u8], context: &ExecutionContext) -> Response<Vec<u8>> {
let request = match decode_batch_request(body, self.config.limits.wire) {
Ok(request) => request,
Err(error) => return self.batch_codec_error(error),
};
let responses = request
.requests
.iter()
.map(|item| {
let outcome = match &item.request {
BatchRequestKind::Fetch(request) => self
.projection
.fetch_with_context(context, &request.path)
.map(BatchSuccess::Fetch)
.map_err(|error| error.protocol_error()),
BatchRequestKind::FetchTree(request) => self
.projection
.fetch_tree(context, request)
.map(BatchSuccess::FetchTree),
BatchRequestKind::FetchInterface(request) => self
.projection
.fetch_interface(request)
.map(BatchSuccess::FetchInterface),
BatchRequestKind::Invalid { error, .. } => Err(error.clone()),
};
BatchResponseItem {
id: item.id.clone(),
outcome,
}
})
.collect();
let response = BatchResponse { responses };
encode_batch_response(&request, &response, self.config.limits.wire).unwrap_or_else(
|error| match error {
EncodeHttpError::Codec(codec) => self.batch_codec_error(codec),
EncodeHttpError::Http(_) => self.batch_top_error(&internal_error(), None),
},
)
}
fn metadata_error(&self, route: Route, error: RequestMetadataError) -> Response<Vec<u8>> {
match error {
RequestMetadataError::InvalidRequest(_) => self.protocol_error(
interaction(route),
&ProtocolError {
code: ProtocolErrorCode::InvalidRequest,
message: "invalid HTTP request metadata".into(),
},
None,
),
RequestMetadataError::UnsupportedMediaType => {
empty_response(StatusCode::UNSUPPORTED_MEDIA_TYPE)
}
RequestMetadataError::NotAcceptable => empty_response(StatusCode::NOT_ACCEPTABLE),
}
}
fn codec_error(
&self,
interaction: ProtocolInteraction,
error: CodecError,
) -> Response<Vec<u8>> {
if let Some(kind) = error.resource_limit_kind() {
self.protocol_error(interaction, &resource_error(), Some(kind))
} else {
self.protocol_error(
interaction,
&ProtocolError {
code: ProtocolErrorCode::InvalidRequest,
message: "malformed WIP request".into(),
},
None,
)
}
}
fn batch_codec_error(&self, error: CodecError) -> Response<Vec<u8>> {
if let Some(kind) = error.resource_limit_kind() {
self.batch_top_error(&resource_error(), Some(kind))
} else {
self.batch_top_error(
&ProtocolError {
code: ProtocolErrorCode::InvalidRequest,
message: "malformed WIP batch request".into(),
},
None,
)
}
}
fn read_encode_error(
&self,
interaction: ProtocolInteraction,
error: EncodeHttpError,
) -> Response<Vec<u8>> {
match error {
EncodeHttpError::Codec(codec) if codec.resource_limit_kind().is_some() => {
self.protocol_error(interaction, &resource_error(), codec.resource_limit_kind())
}
_ => self.protocol_error(interaction, &internal_error(), None),
}
}
fn protocol_error(
&self,
interaction: ProtocolInteraction,
error: &ProtocolError,
resource_kind: Option<ResourceLimitKind>,
) -> Response<Vec<u8>> {
let encoded = match resource_kind {
Some(kind) => encode_resource_limit_error_response(
interaction,
error,
kind,
self.config.limits.wire,
),
None => encode_protocol_error_response(interaction, error, self.config.limits.wire),
};
encoded.unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
}
fn batch_top_error(
&self,
error: &ProtocolError,
resource_kind: Option<ResourceLimitKind>,
) -> Response<Vec<u8>> {
let encoded = match resource_kind {
Some(kind) => {
encode_batch_resource_limit_error_response(error, kind, self.config.limits.wire)
}
None => encode_batch_error_response(error, self.config.limits.wire),
};
encoded.unwrap_or_else(|_| empty_response(StatusCode::INTERNAL_SERVER_ERROR))
}
}
/// Bound real HTTP listener for a [`WipFsServer`].
pub struct BoundServer {
local_addr: SocketAddr,
service: Arc<WipFsServer>,
listener: Arc<TcpListener>,
}
impl BoundServer {
/// Returns the actual bound loopback address, including an assigned port.
#[must_use]
pub fn local_addr(&self) -> SocketAddr {
self.local_addr
}
/// Serves requests with a fixed worker count until `shutdown` becomes true.
///
/// Workers accept connections directly, so at most
/// `max_concurrent_requests` sockets are active in userspace. Each connection
/// is closed after one request and shares one absolute deadline across HTTP
/// intake, dispatch, and response transmission.
pub fn serve_until(&self, shutdown: Arc<AtomicBool>) -> Result<(), std::io::Error> {
let mut workers = Vec::with_capacity(self.service.config.limits.max_concurrent_requests);
for _ in 0..self.service.config.limits.max_concurrent_requests {
let listener = Arc::clone(&self.listener);
let service = Arc::clone(&self.service);
let shutdown = Arc::clone(&shutdown);
workers.push(thread::spawn(move || {
while !shutdown.load(Ordering::Acquire) {
match listener.accept() {
Ok((stream, _)) => serve_connection(&service, stream),
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
thread::sleep(Duration::from_millis(5));
}
Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
Err(error) => return Err(error),
}
}
Ok(())
}));
}
for worker in workers {
worker
.join()
.map_err(|_| std::io::Error::other("HTTP worker panicked"))??;
}
Ok(())
}
/// Serves until the process is terminated.
pub fn serve(&self) -> Result<(), std::io::Error> {
self.serve_until(Arc::new(AtomicBool::new(false)))
}
}
#[derive(Debug)]
struct ParsedRequestHead {
method: http::Method,
target: String,
headers: Vec<(http::header::HeaderName, http::HeaderValue)>,
content_length: usize,
}
#[derive(Debug)]
enum IntakeError {
Timeout,
HeaderTooLarge,
PayloadTooLarge { target: String },
BadRequest,
Socket,
}
fn serve_connection(service: &WipFsServer, mut stream: TcpStream) {
let _ = stream.set_nonblocking(false);
let started = Instant::now();
let deadline = started
.checked_add(service.config.limits.request_timeout)
.unwrap_or(started);
let response = match read_http_request(
&mut stream,
service.config.limits.max_http_header_bytes,
service.config.limits.wire.max_request_bytes(),
deadline,
) {
Ok(request) => Some(service.handle_http_with_deadline(request, deadline)),
Err(IntakeError::HeaderTooLarge) => {
Some(empty_response(StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE))
}
Err(IntakeError::PayloadTooLarge { target }) => {
Some(payload_too_large_response(service, &target))
}
Err(IntakeError::BadRequest) => Some(empty_response(StatusCode::BAD_REQUEST)),
Err(IntakeError::Timeout | IntakeError::Socket) => None,
};
if let Some(response) = response {
let _ = write_http_response(&mut stream, &response, deadline);
}
let _ = stream.shutdown(std::net::Shutdown::Both);
}
fn read_http_request(
stream: &mut TcpStream,
maximum_header: usize,
maximum_body: usize,
deadline: Instant,
) -> Result<Request<Vec<u8>>, IntakeError> {
let mut received = Vec::with_capacity(maximum_header.min(8 * 1024));
let header_end = loop {
if let Some(position) = received.windows(4).position(|window| window == b"\r\n\r\n") {
let end = position + 4;
if end > maximum_header {
return Err(IntakeError::HeaderTooLarge);
}
break end;
}
if received.len() >= maximum_header {
return Err(IntakeError::HeaderTooLarge);
}
let mut chunk = [0_u8; 4 * 1024];
let available = (maximum_header - received.len()).min(chunk.len());
let count = read_with_deadline(stream, &mut chunk[..available], deadline)?;
if count == 0 {
return Err(IntakeError::BadRequest);
}
received.extend_from_slice(&chunk[..count]);
};
let parsed = parse_request_head(&received[..header_end])?;
if parsed.content_length > maximum_body {
return Err(IntakeError::PayloadTooLarge {
target: parsed.target,
});
}
let mut body = Vec::with_capacity(parsed.content_length);
let buffered = &received[header_end..];
body.extend_from_slice(&buffered[..buffered.len().min(parsed.content_length)]);
while body.len() < parsed.content_length {
let mut chunk = [0_u8; 8 * 1024];
let wanted = (parsed.content_length - body.len()).min(chunk.len());
let count = read_with_deadline(stream, &mut chunk[..wanted], deadline)?;
if count == 0 {
return Err(IntakeError::BadRequest);
}
body.extend_from_slice(&chunk[..count]);
}
let mut builder = Request::builder().method(parsed.method).uri(parsed.target);
for (name, value) in parsed.headers {
builder = builder.header(name, value);
}
builder.body(body).map_err(|_| IntakeError::BadRequest)
}
fn parse_request_head(bytes: &[u8]) -> Result<ParsedRequestHead, IntakeError> {
let text = std::str::from_utf8(bytes).map_err(|_| IntakeError::BadRequest)?;
let mut lines = text
.strip_suffix("\r\n\r\n")
.ok_or(IntakeError::BadRequest)?
.split("\r\n");
let mut request_line = lines
.next()
.ok_or(IntakeError::BadRequest)?
.split_ascii_whitespace();
let method = request_line.next().ok_or(IntakeError::BadRequest)?;
let target = request_line.next().ok_or(IntakeError::BadRequest)?;
let version = request_line.next().ok_or(IntakeError::BadRequest)?;
if request_line.next().is_some()
|| !matches!(version, "HTTP/1.0" | "HTTP/1.1")
|| !target.starts_with('/')
{
return Err(IntakeError::BadRequest);
}
let method =
http::Method::from_bytes(method.as_bytes()).map_err(|_| IntakeError::BadRequest)?;
let _: http::Uri = target.parse().map_err(|_| IntakeError::BadRequest)?;
let mut headers = Vec::new();
let mut content_length = None;
for line in lines {
if line.is_empty() || line.starts_with([' ', '\t']) {
return Err(IntakeError::BadRequest);
}
let (name, value) = line.split_once(':').ok_or(IntakeError::BadRequest)?;
let name = http::header::HeaderName::from_bytes(name.as_bytes())
.map_err(|_| IntakeError::BadRequest)?;
let value =
http::HeaderValue::from_str(value.trim()).map_err(|_| IntakeError::BadRequest)?;
if name == http::header::CONTENT_LENGTH {
if content_length.is_some() {
return Err(IntakeError::BadRequest);
}
content_length = Some(
value
.to_str()
.ok()
.and_then(|value| value.parse::<usize>().ok())
.ok_or(IntakeError::BadRequest)?,
);
}
if name == http::header::TRANSFER_ENCODING {
return Err(IntakeError::BadRequest);
}
headers.push((name, value));
}
Ok(ParsedRequestHead {
method,
target: target.to_owned(),
headers,
content_length: content_length.unwrap_or(0),
})
}
fn read_with_deadline(
stream: &mut TcpStream,
buffer: &mut [u8],
deadline: Instant,
) -> Result<usize, IntakeError> {
let remaining = deadline
.checked_duration_since(Instant::now())
.ok_or(IntakeError::Timeout)?;
stream
.set_read_timeout(Some(remaining.max(Duration::from_millis(1))))
.map_err(|_| IntakeError::Socket)?;
stream.read(buffer).map_err(|error| match error.kind() {
std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock => IntakeError::Timeout,
_ => IntakeError::Socket,
})
}
fn payload_too_large_response(service: &WipFsServer, target: &str) -> Response<Vec<u8>> {
let route = service.route(target.split('?').next().unwrap_or_default());
route.map_or_else(
|| empty_response(StatusCode::PAYLOAD_TOO_LARGE),
|route| {
if route == Route::Batch {
service.batch_top_error(
&resource_error(),
Some(ResourceLimitKind::RepresentationBytes),
)
} else {
service.protocol_error(
interaction(route),
&resource_error(),
Some(ResourceLimitKind::RepresentationBytes),
)
}
},
)
}
fn write_http_response(
stream: &mut TcpStream,
response: &Response<Vec<u8>>,
deadline: Instant,
) -> Result<(), std::io::Error> {
let mut encoded = Vec::new();
write!(
encoded,
"HTTP/1.1 {} {}\r\n",
response.status().as_u16(),
response.status().canonical_reason().unwrap_or("")
)?;
for (name, value) in response.headers() {
if name == http::header::CONTENT_LENGTH
|| name == http::header::CONNECTION
|| name == http::header::TRANSFER_ENCODING
{
continue;
}
encoded.extend_from_slice(name.as_str().as_bytes());
encoded.extend_from_slice(b": ");
encoded.extend_from_slice(value.as_bytes());
encoded.extend_from_slice(b"\r\n");
}
write!(
encoded,
"Content-Length: {}\r\nConnection: close\r\n\r\n",
response.body().len()
)?;
encoded.extend_from_slice(response.body());
write_all_with_deadline(stream, &encoded, deadline)
}
fn write_all_with_deadline(
stream: &mut TcpStream,
mut bytes: &[u8],
deadline: Instant,
) -> Result<(), std::io::Error> {
while !bytes.is_empty() {
let remaining = deadline
.checked_duration_since(Instant::now())
.ok_or_else(|| {
std::io::Error::new(std::io::ErrorKind::TimedOut, "request timed out")
})?;
stream.set_write_timeout(Some(remaining.max(Duration::from_millis(1))))?;
match stream.write(bytes) {
Ok(0) => {
return Err(std::io::Error::new(
std::io::ErrorKind::WriteZero,
"socket closed",
));
}
Ok(count) => bytes = &bytes[count..],
Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
Err(error) => return Err(error),
}
}
stream.flush()
}
fn interaction(route: Route) -> ProtocolInteraction {
match route {
Route::Fetch => ProtocolInteraction::Fetch,
Route::FetchTree => ProtocolInteraction::FetchTree,
Route::FetchInterface => ProtocolInteraction::FetchInterface,
Route::CallOperation => ProtocolInteraction::CallOperation,
Route::Batch => ProtocolInteraction::Fetch,
}
}
fn resource_error() -> ProtocolError {
ProtocolError {
code: ProtocolErrorCode::ResourceLimitExceeded,
message: "configured resource limit exceeded".into(),
}
}
fn internal_error() -> ProtocolError {
ProtocolError {
code: ProtocolErrorCode::Internal,
message: "filesystem server failed".into(),
}
}
fn empty_response(status: StatusCode) -> Response<Vec<u8>> {
Response::builder()
.status(status)
.body(Vec::new())
.expect("static status builds an HTTP response")
}
/// Failure while validating, opening, or binding the server.
#[derive(Debug)]
pub enum ServerBuildError {
/// Configuration is unsafe or unbounded.
Config(ConfigError),
/// The root capability could not be opened.
Io(std::io::Error),
/// The listener could not be bound.
Listener(String),
}
impl std::fmt::Display for ServerBuildError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Config(error) => write!(formatter, "invalid server configuration: {error}"),
Self::Io(error) => write!(formatter, "filesystem root could not be opened: {error}"),
Self::Listener(error) => write!(formatter, "HTTP listener could not be bound: {error}"),
}
}
}
impl std::error::Error for ServerBuildError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Config(error) => Some(error),
Self::Io(error) => Some(error),
Self::Listener(_) => None,
}
}
}
impl From<ConfigError> for ServerBuildError {
fn from(value: ConfigError) -> Self {
Self::Config(value)
}
}
impl From<std::io::Error> for ServerBuildError {
fn from(value: std::io::Error) -> Self {
Self::Io(value)
}
}
crates/wip-fs-server/tests/end_to_end.rs
+478
View File
@@ -0,0 +1,478 @@
use std::collections::BTreeMap;
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpStream};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread;
use std::time::{Duration, Instant};
use tempfile::tempdir;
use wip_fs_server::{AccessMode, ServerConfig, TransportSecurity, WipFsServer};
use wip_https::{
BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse, BatchSuccess, DecodedResponse,
Endpoint, JSON_CONTENT_TYPE, Limits, Route, decode_batch_request, decode_batch_response,
decode_call_operation_response, decode_fetch_interface_response, decode_fetch_response,
decode_fetch_tree_response, encode_batch_request, encode_call_operation_request,
encode_fetch_interface_request, encode_fetch_request, encode_fetch_tree_request,
};
use wip_protocol::{
CallOperationRequest, FetchInterfaceRequest, FetchRequest, FetchTreeRequest, InterfaceTarget,
ProtocolErrorCode, Target, Value,
};
#[test]
fn real_listener_serves_four_core_interactions_batch_and_write() {
let temporary = tempdir().expect("temporary root");
std::fs::write(temporary.path().join("hello.txt"), b"hello world").expect("write file");
std::fs::create_dir(temporary.path().join("nested")).expect("create directory");
let mut config = ServerConfig::for_root(temporary.path());
config.access = AccessMode::ReadWrite;
config.transport_security = TransportSecurity::DevelopmentHttp;
let limits = config.limits.wire;
let bound = Arc::new(
WipFsServer::new(config)
.expect("build server")
.bind()
.expect("bind"),
);
let address = bound.local_addr();
let shutdown = Arc::new(AtomicBool::new(false));
let worker = {
let bound = Arc::clone(&bound);
let shutdown = Arc::clone(&shutdown);
thread::spawn(move || bound.serve_until(shutdown))
};
let endpoint = Endpoint::parse(&format!("https://localhost:{}/wip", address.port()))
.expect("client endpoint");
let file_request = FetchRequest {
path: "/hello.txt".into(),
};
let response = exchange(
address,
encode_fetch_request(&endpoint, &file_request, limits).expect("encode fetch"),
);
let file =
success(decode_fetch_response(&file_request, &response, limits).expect("decode fetch"));
assert_eq!(file.name, "hello.txt");
assert_eq!(file.interfaces.len(), 2);
assert!(file.validator.is_some());
let tree_request = FetchTreeRequest {
path: "/".into(),
depth: 1,
limit: 10,
};
let response = exchange(
address,
encode_fetch_tree_request(&endpoint, &tree_request, limits).expect("encode tree"),
);
let tree =
success(decode_fetch_tree_response(&tree_request, &response, limits).expect("decode tree"));
assert!(!tree.truncated);
assert_eq!(tree.root.children.len(), 2);
let read_interface_request = FetchInterfaceRequest {
interface: file.interfaces[0].clone(),
};
let response = exchange(
address,
encode_fetch_interface_request(&endpoint, &read_interface_request, limits)
.expect("encode interface fetch"),
);
let read_interface = success(
decode_fetch_interface_response(&read_interface_request, &response, limits)
.expect("decode interface"),
);
assert_eq!(read_interface.descriptor.operations[0].name, "read");
let read_request = CallOperationRequest {
target: Target {
path: "/hello.txt".into(),
validator: file.validator.clone(),
},
interface: InterfaceTarget {
reference: file.interfaces[0].clone(),
validator: None,
},
operation: "read".into(),
arguments: BTreeMap::from([
("offset".into(), Value::Integer(6)),
("length".into(), Value::Integer(5)),
]),
};
let response = exchange(
address,
encode_call_operation_request(&endpoint, &read_request, &read_interface.descriptor, limits)
.expect("encode read call"),
);
let read = success(
decode_call_operation_response(
&read_request,
&read_interface.descriptor,
&response,
limits,
)
.expect("decode read call"),
);
assert_eq!(read.result, Value::Bytes(b"world".to_vec()));
let batch_request = BatchRequest {
requests: vec![
BatchRequestItem {
id: "root".into(),
request: BatchRequestKind::Fetch(FetchRequest { path: "/".into() }),
},
BatchRequestItem {
id: "tree".into(),
request: BatchRequestKind::FetchTree(FetchTreeRequest {
path: "/nested".into(),
depth: 1,
limit: 4,
}),
},
BatchRequestItem {
id: "interface".into(),
request: BatchRequestKind::FetchInterface(read_interface_request.clone()),
},
],
};
let response = exchange(
address,
encode_batch_request(&endpoint, &batch_request, limits).expect("encode batch"),
);
let batch =
success(decode_batch_response(&batch_request, &response, limits).expect("decode batch"));
assert_batch_successes(&batch);
let write_interface_request = FetchInterfaceRequest {
interface: file.interfaces[1].clone(),
};
let response = exchange(
address,
encode_fetch_interface_request(&endpoint, &write_interface_request, limits)
.expect("encode write interface fetch"),
);
let write_interface = success(
decode_fetch_interface_response(&write_interface_request, &response, limits)
.expect("decode write interface"),
);
let write_request = CallOperationRequest {
target: Target {
path: "/hello.txt".into(),
validator: file.validator,
},
interface: InterfaceTarget {
reference: file.interfaces[1].clone(),
validator: None,
},
operation: "replace".into(),
arguments: BTreeMap::from([("contents".into(), Value::Bytes(b"updated".to_vec()))]),
};
let response = exchange(
address,
encode_call_operation_request(
&endpoint,
&write_request,
&write_interface.descriptor,
limits,
)
.expect("encode write call"),
);
let write = success(
decode_call_operation_response(
&write_request,
&write_interface.descriptor,
&response,
limits,
)
.expect("decode write call"),
);
assert!(write.validator.is_some());
assert_eq!(
std::fs::read(temporary.path().join("hello.txt")).expect("read updated file"),
b"updated"
);
shutdown.store(true, Ordering::Release);
worker
.join()
.expect("join listener")
.expect("listener exits cleanly");
}
#[test]
fn stalled_request_body_times_out_and_releases_the_only_worker() {
let temporary = tempdir().expect("temporary root");
let mut config = ServerConfig::for_root(temporary.path());
config.transport_security = TransportSecurity::DevelopmentHttp;
config.limits.max_concurrent_requests = 1;
config.limits.request_timeout = Duration::from_millis(200);
let limits = config.limits.wire;
let bound = Arc::new(
WipFsServer::new(config)
.expect("build server")
.bind()
.expect("bind"),
);
let address = bound.local_addr();
let shutdown = Arc::new(AtomicBool::new(false));
let worker = {
let bound = Arc::clone(&bound);
let shutdown = Arc::clone(&shutdown);
thread::spawn(move || bound.serve_until(shutdown))
};
let mut stalled = TcpStream::connect(address).expect("connect stalled client");
stalled
.set_read_timeout(Some(Duration::from_secs(1)))
.expect("set stalled read timeout");
write!(
stalled,
"POST /wip/v1/fetch HTTP/1.1\r\nHost: localhost\r\nContent-Type: application/json\r\nAccept: application/json\r\nContent-Length: 100\r\n\r\n{{"
)
.expect("write partial request");
stalled.flush().expect("flush partial request");
thread::sleep(Duration::from_millis(25));
let endpoint = Endpoint::parse(&format!("https://localhost:{}/wip", address.port()))
.expect("client endpoint");
let fetch = FetchRequest { path: "/".into() };
let started = Instant::now();
let response = exchange(
address,
encode_fetch_request(&endpoint, &fetch, limits).expect("encode fetch"),
);
let _root = success(decode_fetch_response(&fetch, &response, limits).expect("decode fetch"));
assert!(
started.elapsed() < Duration::from_secs(1),
"the valid request remained starved after the intake deadline"
);
let mut byte = [0_u8; 1];
match stalled.read(&mut byte) {
Ok(0) => {}
Err(error)
if matches!(
error.kind(),
std::io::ErrorKind::ConnectionReset
| std::io::ErrorKind::ConnectionAborted
| std::io::ErrorKind::BrokenPipe
) => {}
outcome => panic!("stalled connection was not closed after its deadline: {outcome:?}"),
}
shutdown.store(true, Ordering::Release);
worker
.join()
.expect("join listener")
.expect("listener exits cleanly");
}
#[test]
fn batch_keeps_known_malformed_arguments_item_local() {
let temporary = tempdir().expect("temporary root");
let config = ServerConfig::for_root(temporary.path());
let limits = config.limits.wire;
let server = WipFsServer::new(config).expect("build server");
let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
let body = br#"{"requests":[{"id":"ok","method":"fetch","arguments":{"path":"/"}},{"id":"bad","method":"fetch_tree","arguments":{"path":"/","depth":"bad","limit":1}}]}"#;
let logical = decode_batch_request(body, limits).expect("decode item-local invalid request");
assert!(matches!(
logical.requests[1].request,
BatchRequestKind::Invalid { .. }
));
let request = http::Request::builder()
.method(http::Method::POST)
.uri(endpoint.route(Route::Batch).as_str())
.header(http::header::CONTENT_TYPE, JSON_CONTENT_TYPE)
.header(http::header::ACCEPT, "application/json")
.body(body.to_vec())
.expect("build request");
let response = server.handle_http(request);
let batch = success(
decode_batch_response(&logical, &response, limits).expect("decode mixed batch response"),
);
assert!(matches!(
batch.responses[0].outcome,
Ok(BatchSuccess::Fetch(_))
));
assert!(batch.responses[1].outcome.is_err());
}
#[test]
fn call_argument_decoding_does_not_mask_missing_target() {
let temporary = tempdir().expect("temporary root");
let config = ServerConfig::for_root(temporary.path());
let server = WipFsServer::new(config).expect("build server");
let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
let body = br#"{"target":{"path":"/missing"},"interface":{"reference":"unknown"},"operation":"missing","arguments":{"bytes":"not-base64"}}"#;
let request = http::Request::builder()
.method(http::Method::POST)
.uri(endpoint.route(Route::CallOperation).as_str())
.header(http::header::CONTENT_TYPE, JSON_CONTENT_TYPE)
.header(http::header::ACCEPT, "application/json")
.body(body.to_vec())
.expect("build request");
let response = server.handle_http(request);
assert_eq!(response.status(), http::StatusCode::NOT_FOUND);
assert!(
std::str::from_utf8(response.body())
.expect("UTF-8 error")
.contains("\"not_found\"")
);
}
#[test]
fn backend_invalid_unicode_path_is_not_found_not_internal() {
let temporary = tempdir().expect("temporary root");
let config = ServerConfig::for_root(temporary.path());
let limits = config.limits.wire;
let server = WipFsServer::new(config).expect("build server");
let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
let request = FetchRequest {
path: "/bad\0name".into(),
};
let response = server
.handle_http(encode_fetch_request(&endpoint, &request, limits).expect("encode fetch"));
assert_eq!(response.status(), http::StatusCode::NOT_FOUND);
match decode_fetch_response(&request, &response, limits).expect("decode missing response") {
DecodedResponse::ProtocolFailure { error, .. } => {
assert_eq!(error.code, ProtocolErrorCode::NotFound);
}
DecodedResponse::Success(_) => panic!("backend-invalid path must not resolve"),
}
}
#[test]
fn read_response_size_failure_preserves_non_commit_guarantee() {
let temporary = tempdir().expect("temporary root");
std::fs::write(temporary.path().join("large"), vec![b'x'; 2_000]).expect("write file");
let mut config = ServerConfig::for_root(temporary.path());
config.limits.wire = Limits::new(4_096, 1_024, 64, 64).expect("wire limits");
let limits = config.limits.wire;
let server = WipFsServer::new(config).expect("build server");
let endpoint = Endpoint::parse("https://localhost/wip").expect("endpoint");
let fetch_request = FetchRequest {
path: "/large".into(),
};
let response = server.handle_http(
encode_fetch_request(&endpoint, &fetch_request, limits).expect("encode fetch"),
);
let file =
success(decode_fetch_response(&fetch_request, &response, limits).expect("decode fetch"));
let interface_request = FetchInterfaceRequest {
interface: file.interfaces[0].clone(),
};
let response = server.handle_http(
encode_fetch_interface_request(&endpoint, &interface_request, limits)
.expect("encode interface fetch"),
);
let interface = success(
decode_fetch_interface_response(&interface_request, &response, limits)
.expect("decode interface"),
);
let call = CallOperationRequest {
target: Target {
path: "/large".into(),
validator: file.validator,
},
interface: InterfaceTarget {
reference: file.interfaces[0].clone(),
validator: None,
},
operation: "read".into(),
arguments: BTreeMap::from([("length".into(), Value::Integer(1_500))]),
};
let response = server.handle_http(
encode_call_operation_request(&endpoint, &call, &interface.descriptor, limits)
.expect("encode read call"),
);
assert_eq!(response.status(), http::StatusCode::PAYLOAD_TOO_LARGE);
match decode_call_operation_response(&call, &interface.descriptor, &response, limits)
.expect("decode resource failure")
{
DecodedResponse::ProtocolFailure { error, .. } => {
assert_eq!(error.code, ProtocolErrorCode::ResourceLimitExceeded);
}
DecodedResponse::Success(_) => panic!("oversized read response must fail"),
}
}
fn assert_batch_successes(batch: &BatchResponse) {
assert_eq!(batch.responses.len(), 3);
assert!(matches!(
batch.responses[0].outcome,
Ok(BatchSuccess::Fetch(_))
));
assert!(matches!(
batch.responses[1].outcome,
Ok(BatchSuccess::FetchTree(_))
));
assert!(matches!(
batch.responses[2].outcome,
Ok(BatchSuccess::FetchInterface(_))
));
}
fn success<T>(response: DecodedResponse<T>) -> T {
match response {
DecodedResponse::Success(value) => value,
DecodedResponse::ProtocolFailure { error, .. } => panic!("protocol failure: {error}"),
}
}
fn exchange(address: SocketAddr, request: http::Request<Vec<u8>>) -> http::Response<Vec<u8>> {
let mut stream = TcpStream::connect(address).expect("connect listener");
stream
.set_read_timeout(Some(Duration::from_secs(5)))
.expect("set read timeout");
let path = request
.uri()
.path_and_query()
.map_or("/", |value| value.as_str());
write!(
stream,
"{} {} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n",
request.method(),
path
)
.expect("write request line");
for (name, value) in request.headers() {
write!(
stream,
"{}: {}\r\n",
name,
value.to_str().expect("ASCII request header")
)
.expect("write header");
}
write!(stream, "Content-Length: {}\r\n\r\n", request.body().len())
.expect("write content length");
stream.write_all(request.body()).expect("write body");
stream.flush().expect("flush request");
let mut raw = Vec::new();
stream.read_to_end(&mut raw).expect("read response");
let split = raw
.windows(4)
.position(|window| window == b"\r\n\r\n")
.expect("HTTP response header");
let head = std::str::from_utf8(&raw[..split]).expect("UTF-8 response head");
let mut lines = head.split("\r\n");
let status = lines
.next()
.and_then(|line| line.split_whitespace().nth(1))
.and_then(|status| status.parse::<u16>().ok())
.expect("response status");
let mut builder = http::Response::builder().status(status);
for line in lines {
let (name, value) = line.split_once(':').expect("response header");
builder = builder.header(name, value.trim());
}
builder
.body(raw[split + 4..].to_vec())
.expect("build response")
}
crates/wip-host/src/lib.rs
+115 -28
View File
@@ -535,11 +535,36 @@ impl<T: WipObject> PublishedObject<T> {
context: &ExecutionContext,
request: CallRequest,
authorize: impl FnOnce(&T, &InterfaceRef, &str) -> bool,
) -> OperationAttempt {
let CallRequest {
target,
interface,
operation,
arguments,
} = request;
self.dispatch_resolved_with_decoder(
context,
target,
interface,
operation,
|_| Ok::<_, std::convert::Infallible>(arguments),
authorize,
)
}
fn dispatch_resolved_with_decoder<E>(
&self,
context: &ExecutionContext,
target: Target,
interface: InterfaceTarget,
operation: String,
decode_arguments: impl FnOnce(&InterfaceDescriptor) -> Result<BTreeMap<String, Value>, E>,
authorize: impl FnOnce(&T, &InterfaceRef, &str) -> bool,
) -> OperationAttempt {
let pre_dispatch_failure =
|kind, message: &str| OperationAttempt::NotStarted(CallError::new(kind, message));
let current_object_validator = self.implementation.validator();
if let Some(supplied) = request.target.validator.as_deref()
if let Some(supplied) = target.validator.as_deref()
&& current_object_validator.map(Validator::as_bytes) != Some(supplied)
{
return pre_dispatch_failure(
@@ -548,9 +573,11 @@ impl<T: WipObject> PublishedObject<T> {
);
}
let Some(bound) = self.interfaces.iter().find(|bound| {
bound.artifact.reference.as_str() == request.interface.reference.as_str()
}) else {
let Some(bound) = self
.interfaces
.iter()
.find(|bound| bound.artifact.reference.as_str() == interface.reference.as_str())
else {
return pre_dispatch_failure(
CallErrorKind::InterfaceMismatch,
"interface is not a member of the current object publication",
@@ -559,7 +586,7 @@ impl<T: WipObject> PublishedObject<T> {
match (
bound.artifact.validator.as_ref(),
request.interface.validator.as_deref(),
interface.validator.as_deref(),
) {
(Some(_), None) => {
return pre_dispatch_failure(
@@ -581,18 +608,18 @@ impl<T: WipObject> PublishedObject<T> {
.descriptor
.operations
.iter()
.any(|operation| operation.name == request.operation)
.any(|declared| declared.name == operation)
{
return pre_dispatch_failure(
CallErrorKind::OperationNotFound,
&format!("operation `{}` is not declared", request.operation),
&format!("operation `{operation}` is not declared"),
);
}
if request.target.validator.is_none()
if target.validator.is_none()
&& self
.implementation
.requires_validator(&bound.artifact.reference, &request.operation)
.requires_validator(&bound.artifact.reference, &operation)
{
return pre_dispatch_failure(
CallErrorKind::ValidatorRequired,
@@ -600,19 +627,24 @@ impl<T: WipObject> PublishedObject<T> {
);
}
let arguments = match decode_arguments(&bound.artifact.descriptor) {
Ok(arguments) => arguments,
Err(_) => {
return pre_dispatch_failure(
CallErrorKind::InvalidArguments,
"operation arguments could not be decoded",
);
}
};
if let Err(error) = bound
.artifact
.descriptor
.validate_arguments(&request.operation, &request.arguments)
.validate_arguments(&operation, &arguments)
{
return pre_dispatch_failure(CallErrorKind::InvalidArguments, &error.to_string());
}
if !authorize(
&self.implementation,
&bound.artifact.reference,
&request.operation,
) {
if !authorize(&self.implementation, &bound.artifact.reference, &operation) {
return pre_dispatch_failure(
CallErrorKind::PermissionDenied,
"operation is not permitted for this caller",
@@ -623,23 +655,22 @@ impl<T: WipObject> PublishedObject<T> {
return OperationAttempt::NotStarted(error);
}
let value =
match (bound.dispatch)(&self.implementation, &request.operation, request.arguments) {
Ok(value) => value,
Err(
error @ (DispatchError::UnknownOperation(_)
| DispatchError::InvalidArguments(_)
| DispatchError::Decode(_)),
) => return OperationAttempt::NotStarted(CallError::from_pre_dispatch(error)),
Err(error) => {
return OperationAttempt::Started(Err(OperationFailure::from_dispatch(error)));
}
};
let value = match (bound.dispatch)(&self.implementation, &operation, arguments) {
Ok(value) => value,
Err(
error @ (DispatchError::UnknownOperation(_)
| DispatchError::InvalidArguments(_)
| DispatchError::Decode(_)),
) => return OperationAttempt::NotStarted(CallError::from_pre_dispatch(error)),
Err(error) => {
return OperationAttempt::Started(Err(OperationFailure::from_dispatch(error)));
}
};
if bound
.artifact
.descriptor
.validate_result(&request.operation, &value)
.validate_result(&operation, &value)
.is_err()
{
return OperationAttempt::Started(Err(OperationFailure::internal(
@@ -922,6 +953,62 @@ pub trait ObjectProvider {
ProviderResult::Failure(error) => Err(CallError::from_host_failure(error)),
}
}
/// Resolves one operation target and decodes its arguments only after all
/// descriptor-independent canonical preconditions have succeeded.
///
/// Transport bindings whose value representation depends on the selected
/// interface descriptor should use this method instead of resolving a
/// descriptor before [`ObjectProvider::call_operation_with_context`]. The
/// callback executes inside the same exact-once provider boundary after
/// object/interface validators, membership, operation lookup, and required
/// object-validator checks. A callback error becomes `InvalidArguments` and
/// typed implementation code is not invoked.
fn call_operation_with_context_and_decoder<E>(
&self,
context: &ExecutionContext,
target: Target,
interface: InterfaceTarget,
operation: String,
decode_arguments: impl FnOnce(&InterfaceDescriptor) -> Result<BTreeMap<String, Value>, E>,
) -> Result<CallResult, CallError> {
wip_protocol::validate_path(&target.path)
.map_err(|error| CallError::new(CallErrorKind::InvalidRequest, error.to_string()))?;
let path = target.path.clone();
let execution = catch_unwind(AssertUnwindSafe(|| {
self.execute_operation(context, &path, |publication| {
publication.dispatch_resolved_with_decoder(
context,
target,
interface,
operation,
decode_arguments,
|object, interface, operation| {
self.authorize(&path, object, interface, operation)
},
)
})
}));
let execution = execution.map_err(|_| {
CallError::from_operation_failure(OperationFailure::internal(
EffectGuarantee::Unknown,
"provider execution panicked",
))
})?;
match execution {
ProviderResult::Found(OperationAttempt::NotStarted(error)) => Err(error),
ProviderResult::Found(OperationAttempt::Started(Ok(result))) => Ok(result),
ProviderResult::Found(OperationAttempt::Started(Err(error))) => {
Err(CallError::from_operation_failure(error))
}
ProviderResult::NotFound => Err(CallError::new(
CallErrorKind::NotFound,
"target path is not published",
)),
ProviderResult::Failure(error) => Err(CallError::from_host_failure(error)),
}
}
}
/// Failure to construct an explicit object publication.
crates/wip-host/tests/host.rs
+83
View File
@@ -741,6 +741,89 @@ fn call_failures_follow_canonical_precedence_without_execution() {
assert_eq!(provider.calls.get(), 0);
}
#[test]
fn descriptor_guided_decoder_runs_inside_canonical_resolution_boundary() {
let (_, provider, hidden) = registry_and_provider();
let decodes = Cell::new(0_u32);
let decode_failure = || {
decodes.set(decodes.get() + 1);
Err::<BTreeMap<String, Value>, _>(())
};
let missing = provider
.call_operation_with_context_and_decoder(
&ExecutionContext::new(),
Target {
path: "/missing".into(),
validator: Some(b"stale".to_vec()),
},
InterfaceTarget {
reference: hidden.reference().as_str().into(),
validator: None,
},
"missing".into(),
|_| decode_failure(),
)
.unwrap_err();
assert_eq!(missing.kind(), CallErrorKind::NotFound);
assert_eq!(decodes.get(), 0);
let stale = provider
.call_operation_with_context_and_decoder(
&ExecutionContext::new(),
Target {
path: "/document".into(),
validator: Some(b"stale".to_vec()),
},
InterfaceTarget {
reference: hidden.reference().as_str().into(),
validator: None,
},
"hidden".into(),
|_| decode_failure(),
)
.unwrap_err();
assert_eq!(stale.kind(), CallErrorKind::ValidatorMismatch);
assert_eq!(decodes.get(), 0);
let mismatch = provider
.call_operation_with_context_and_decoder(
&ExecutionContext::new(),
Target {
path: "/document".into(),
validator: Some(b"object-v1".to_vec()),
},
InterfaceTarget {
reference: hidden.reference().as_str().into(),
validator: None,
},
"hidden".into(),
|_| decode_failure(),
)
.unwrap_err();
assert_eq!(mismatch.kind(), CallErrorKind::InterfaceMismatch);
assert_eq!(decodes.get(), 0);
let invalid_arguments = provider
.call_operation_with_context_and_decoder(
&ExecutionContext::new(),
Target {
path: "/document".into(),
validator: Some(b"object-v1".to_vec()),
},
InterfaceTarget {
reference: provider.reader.reference().as_str().into(),
validator: Some(b"schema-v1".to_vec()),
},
"add".into(),
|_| decode_failure(),
)
.unwrap_err();
assert_eq!(invalid_arguments.kind(), CallErrorKind::InvalidArguments);
assert_eq!(decodes.get(), 1);
assert_eq!(provider.calls.get(), 0);
}
#[test]
fn immutable_interface_rejects_a_supplied_validator() {
let (_, provider, _) = registry_and_provider();
crates/wip-https/Cargo.toml
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "wip-https"
version = "0.1.0"
edition = "2024"
description = "Framework-independent standard WIP over HTTPS v1 binding"
license = "MIT OR Apache-2.0"
[dependencies]
base64 = "0.22"
http = "1"
serde = "1"
serde_json = "1"
url = "2"
wip-protocol = { path = "../wip-protocol" }
crates/wip-https/src/batch.rs
+596
View File
@@ -0,0 +1,596 @@
use std::collections::{BTreeMap, BTreeSet};
use http::header::{ACCEPT, CONTENT_TYPE};
use http::{Method, Request, Response, StatusCode};
use serde_json::{Map, Value as Json};
use wip_protocol::{
FetchInterfaceRequest, FetchInterfaceResponse, FetchRequest, FetchResponse, FetchTreeRequest,
FetchTreeResponse, INTERFACE_FORMAT_V1, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
};
use crate::response::{self, DecodedResponse};
use crate::{
BodyKind, ClientResponseError, CodecError, EncodeHttpError, Endpoint, InvalidResponseKind,
JSON_CONTENT_TYPE, Limits, ResourceLimitKind, Route, is_json_content_type, json,
};
/// A retrieval method accepted by the standard v1 batch endpoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BatchMethod {
/// Fetch one object.
Fetch,
/// Fetch one bounded tree.
FetchTree,
/// Fetch one interface descriptor.
FetchInterface,
}
impl BatchMethod {
fn name(self) -> &'static str {
match self {
Self::Fetch => "fetch",
Self::FetchTree => "fetch_tree",
Self::FetchInterface => "fetch_interface",
}
}
fn interaction(self) -> ProtocolInteraction {
match self {
Self::Fetch => ProtocolInteraction::Fetch,
Self::FetchTree => ProtocolInteraction::FetchTree,
Self::FetchInterface => ProtocolInteraction::FetchInterface,
}
}
}
/// One retrieval interaction accepted by the standard v1 batch endpoint.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BatchRequestKind {
/// Fetch one object.
Fetch(FetchRequest),
/// Fetch one bounded tree.
FetchTree(FetchTreeRequest),
/// Fetch one interface descriptor.
FetchInterface(FetchInterfaceRequest),
/// A known method whose `arguments` are not a valid logical request.
Invalid {
/// Method that was successfully identified from the item envelope.
method: BatchMethod,
/// Item-local `invalid_request` to return without rejecting other items.
error: ProtocolError,
},
}
impl BatchRequestKind {
fn interaction(&self) -> ProtocolInteraction {
match self {
Self::Fetch(_) => ProtocolInteraction::Fetch,
Self::FetchTree(_) => ProtocolInteraction::FetchTree,
Self::FetchInterface(_) => ProtocolInteraction::FetchInterface,
Self::Invalid { method, .. } => method.interaction(),
}
}
}
/// One uniquely identified batch subrequest.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BatchRequestItem {
/// Identifier used only to correlate the corresponding subresponse.
pub id: String,
/// Retrieval interaction and arguments.
pub request: BatchRequestKind,
}
/// A standard v1 batch request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BatchRequest {
/// Independent subrequests. Identifiers must be unique.
pub requests: Vec<BatchRequestItem>,
}
/// Successful result of one batch item.
#[derive(Debug, Clone, PartialEq)]
pub enum BatchSuccess {
/// Successful `fetch` result.
Fetch(FetchResponse),
/// Successful `fetch_tree` result.
FetchTree(FetchTreeResponse),
/// Successful `fetch_interface` result.
FetchInterface(FetchInterfaceResponse),
}
/// One batch subresponse, correlated by `id` rather than array position.
#[derive(Debug, Clone, PartialEq)]
pub struct BatchResponseItem {
/// Identifier copied from its subrequest.
pub id: String,
/// Direct interaction result or canonical item-local protocol failure.
pub outcome: Result<BatchSuccess, ProtocolError>,
}
/// A valid standard v1 batch response.
#[derive(Debug, Clone, PartialEq)]
pub struct BatchResponse {
/// Exactly one response for each requested identifier, in any order.
pub responses: Vec<BatchResponseItem>,
}
fn validate_ids<'a>(ids: impl Iterator<Item = &'a str>, maximum: usize) -> Result<(), CodecError> {
let mut seen = BTreeSet::new();
let mut count = 0;
for id in ids {
count += 1;
if !seen.insert(id) {
return Err(CodecError::DuplicateBatchId { id: id.into() });
}
}
if count > maximum {
return Err(CodecError::TooManyBatchItems {
actual: count,
maximum,
});
}
Ok(())
}
fn request_item_to_json(item: &BatchRequestItem) -> Result<Json, CodecError> {
let (method, arguments) = match &item.request {
BatchRequestKind::Fetch(value) => ("fetch", json::fetch_request_to_json(value)),
BatchRequestKind::FetchTree(value) => {
("fetch_tree", json::fetch_tree_request_to_json(value))
}
BatchRequestKind::FetchInterface(value) => (
"fetch_interface",
json::fetch_interface_request_to_json(value),
),
BatchRequestKind::Invalid { .. } => {
return Err(CodecError::InvalidField {
field: "requests".into(),
reason: "item-local invalid requests cannot be encoded as client requests".into(),
});
}
};
Ok(serde_json::json!({"id": item.id, "method": method, "arguments": arguments}))
}
fn request_to_json(request: &BatchRequest, limits: Limits) -> Result<Json, CodecError> {
validate_ids(
request.requests.iter().map(|item| item.id.as_str()),
limits.max_batch_items,
)?;
for item in &request.requests {
match &item.request {
BatchRequestKind::Fetch(value) => value.validate()?,
BatchRequestKind::FetchTree(value) => value.validate()?,
BatchRequestKind::FetchInterface(_) | BatchRequestKind::Invalid { .. } => {}
}
}
let requests = request
.requests
.iter()
.map(request_item_to_json)
.collect::<Result<Vec<_>, _>>()?;
Ok(serde_json::json!({"requests": requests}))
}
fn request_from_json(value: &Json, limits: Limits) -> Result<BatchRequest, CodecError> {
let fields = exact_object(value, "batch", &["requests"])?;
let values = array(required(fields, "requests")?, "requests")?;
if values.len() > limits.max_batch_items {
return Err(CodecError::TooManyBatchItems {
actual: values.len(),
maximum: limits.max_batch_items,
});
}
let mut requests = Vec::with_capacity(values.len());
for (index, value) in values.iter().enumerate() {
let field = format!("requests[{index}]");
let fields = exact_object(value, &field, &["id", "method", "arguments"])?;
let id = string(required(fields, "id")?, &format!("{field}.id"))?;
let method_name = string(required(fields, "method")?, &format!("{field}.method"))?;
let arguments = required(fields, "arguments")?;
let method = match method_name.as_str() {
"fetch" => BatchMethod::Fetch,
"fetch_tree" => BatchMethod::FetchTree,
"fetch_interface" => BatchMethod::FetchInterface,
_ => {
return Err(CodecError::InvalidField {
field: format!("{field}.method"),
reason: "batch supports only fetch, fetch_tree, and fetch_interface".into(),
});
}
};
let decoded = match method {
BatchMethod::Fetch => {
json::fetch_request_from_json(arguments).map(BatchRequestKind::Fetch)
}
BatchMethod::FetchTree => {
json::fetch_tree_request_from_json(arguments).map(BatchRequestKind::FetchTree)
}
BatchMethod::FetchInterface => json::fetch_interface_request_from_json(arguments)
.map(BatchRequestKind::FetchInterface),
};
let request = decoded.unwrap_or_else(|error| BatchRequestKind::Invalid {
method,
error: ProtocolError {
code: ProtocolErrorCode::InvalidRequest,
message: format!("invalid {} arguments: {error}", method.name()),
},
});
requests.push(BatchRequestItem { id, request });
}
validate_ids(
requests.iter().map(|item| item.id.as_str()),
limits.max_batch_items,
)?;
Ok(BatchRequest { requests })
}
/// Encodes a batch request using `POST v1/batch`.
pub fn encode_batch_request(
endpoint: &Endpoint,
value: &BatchRequest,
limits: Limits,
) -> Result<Request<Vec<u8>>, EncodeHttpError> {
let body = json::serialize(&request_to_json(value, limits)?, BodyKind::Request, limits)?;
Ok(Request::builder()
.method(Method::POST)
.uri(endpoint.route(Route::Batch).as_str())
.header(CONTENT_TYPE, JSON_CONTENT_TYPE)
.header(ACCEPT, "application/json")
.body(body)?)
}
/// Decodes and validates a batch request body.
pub fn decode_batch_request(body: &[u8], limits: Limits) -> Result<BatchRequest, CodecError> {
let value = json::parse(body, BodyKind::Request, limits)?;
request_from_json(&value, limits)
}
fn success_to_json(success: &BatchSuccess) -> Json {
match success {
BatchSuccess::Fetch(value) => json::object_to_json(value),
BatchSuccess::FetchTree(value) => json::fetch_tree_response_to_json(value),
BatchSuccess::FetchInterface(value) => json::fetch_interface_response_to_json(value),
}
}
fn response_to_json(
request: &BatchRequest,
response: &BatchResponse,
limits: Limits,
) -> Result<Json, CodecError> {
correlate(request, response, limits)?;
Ok(serde_json::json!({
"responses": response.responses.iter().map(|item| {
let mut fields = Map::new();
fields.insert("id".into(), Json::String(item.id.clone()));
match &item.outcome {
Ok(success) => { fields.insert("result".into(), success_to_json(success)); }
Err(error) => { fields.insert("error".into(), response::item_error_to_json(error)); }
}
Json::Object(fields)
}).collect::<Vec<_>>()
}))
}
fn correlate(
request: &BatchRequest,
response: &BatchResponse,
limits: Limits,
) -> Result<(), CodecError> {
validate_ids(
request.requests.iter().map(|item| item.id.as_str()),
limits.max_batch_items,
)?;
validate_ids(
response.responses.iter().map(|item| item.id.as_str()),
limits.max_batch_items,
)?;
let requested: BTreeMap<&str, &BatchRequestKind> = request
.requests
.iter()
.map(|item| (item.id.as_str(), &item.request))
.collect();
for item in &response.responses {
let Some(kind) = requested.get(item.id.as_str()) else {
return Err(CodecError::UnexpectedBatchId {
id: item.id.clone(),
});
};
match (&item.outcome, *kind) {
(Ok(BatchSuccess::Fetch(value)), BatchRequestKind::Fetch(request)) => {
request.validate_response(value)?;
}
(Ok(BatchSuccess::FetchTree(value)), BatchRequestKind::FetchTree(request)) => {
value.validate_for(request)?;
}
(
Ok(BatchSuccess::FetchInterface(value)),
BatchRequestKind::FetchInterface(request),
) => {
value.validate_for(request)?;
}
(
Err(error),
BatchRequestKind::Invalid {
error: expected, ..
},
) if error == expected => {}
(Err(error), kind)
if !matches!(kind, BatchRequestKind::Invalid { .. })
&& error.code.is_allowed_for(kind.interaction()) => {}
_ => {
return Err(CodecError::BatchInteractionMismatch {
id: item.id.clone(),
});
}
}
}
for item in &request.requests {
if !response.responses.iter().any(|other| other.id == item.id) {
return Err(CodecError::MissingBatchId {
id: item.id.clone(),
});
}
}
Ok(())
}
/// Encodes a valid batch response. Item failures remain inside HTTP 200.
pub fn encode_batch_response(
request: &BatchRequest,
value: &BatchResponse,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
let body = json::serialize(
&response_to_json(request, value, limits)?,
BodyKind::Response,
limits,
)?;
Ok(Response::builder()
.status(StatusCode::OK)
.header(CONTENT_TYPE, JSON_CONTENT_TYPE)
.body(body)?)
}
/// Encodes a top-level batch-envelope failure.
///
/// Item-local failures belong in [`BatchResponseItem`]. Only failures that can
/// reject the batch envelope before item execution are accepted here. A
/// resource-limit failure defaults to the logical-limit status; use
/// [`encode_batch_resource_limit_error_response`] when the concrete class is
/// known.
pub fn encode_batch_error_response(
error: &ProtocolError,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
if !matches!(
error.code,
ProtocolErrorCode::InvalidRequest
| ProtocolErrorCode::ResourceLimitExceeded
| ProtocolErrorCode::Internal
) {
return Err(CodecError::InvalidField {
field: "error.code".into(),
reason: "code is not valid for a top-level batch failure".into(),
}
.into());
}
let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
Ok(Response::builder()
.status(response::status_for_error(error.code))
.header(CONTENT_TYPE, JSON_CONTENT_TYPE)
.body(body)?)
}
/// Encodes a class-specific top-level batch `resource_limit_exceeded` failure.
pub fn encode_batch_resource_limit_error_response(
error: &ProtocolError,
kind: ResourceLimitKind,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
if error.code != ProtocolErrorCode::ResourceLimitExceeded {
return Err(CodecError::InvalidField {
field: "error.code".into(),
reason: "resource-limit encoder requires resource_limit_exceeded".into(),
}
.into());
}
let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
Ok(Response::builder()
.status(response::status_for_resource_limit(kind))
.header(CONTENT_TYPE, JSON_CONTENT_TYPE)
.body(body)?)
}
fn response_from_json(
value: &Json,
request: &BatchRequest,
limits: Limits,
) -> Result<BatchResponse, CodecError> {
let fields = exact_object(value, "batch", &["responses"])?;
let values = array(required(fields, "responses")?, "responses")?;
if values.len() > limits.max_batch_items {
return Err(CodecError::TooManyBatchItems {
actual: values.len(),
maximum: limits.max_batch_items,
});
}
let requested: BTreeMap<&str, &BatchRequestKind> = request
.requests
.iter()
.map(|item| (item.id.as_str(), &item.request))
.collect();
let mut responses = Vec::with_capacity(values.len());
for (index, value) in values.iter().enumerate() {
let field = format!("responses[{index}]");
let fields = object(value, &field)?;
for name in fields.keys() {
if !["id", "result", "error"].contains(&name.as_str()) {
return Err(CodecError::UnknownField {
field: format!("{field}.{name}"),
});
}
}
let id = string(required(fields, "id")?, &format!("{field}.id"))?;
let Some(kind) = requested.get(id.as_str()) else {
return Err(CodecError::UnexpectedBatchId { id });
};
let outcome = match (fields.get("result"), fields.get("error")) {
(Some(_), Some(_)) | (None, None) => {
return Err(CodecError::InvalidField {
field,
reason: "batch item must contain exactly one of result or error".into(),
});
}
(None, Some(error)) => {
let error = response::item_error_from_json(error)?;
match kind {
BatchRequestKind::Invalid {
error: expected, ..
} if error == *expected => {}
BatchRequestKind::Invalid { .. } => {
return Err(CodecError::BatchInteractionMismatch { id });
}
kind if error.code.is_allowed_for(kind.interaction()) => {}
_ => return Err(CodecError::BatchInteractionMismatch { id }),
}
Err(error)
}
(Some(result), None) => Ok(match kind {
BatchRequestKind::Fetch(request) => {
let value = json::object_from_json(result, "result")?;
request.validate_response(&value)?;
BatchSuccess::Fetch(value)
}
BatchRequestKind::FetchTree(request) => {
let value = json::fetch_tree_response_from_json(result)?;
value.validate_for(request)?;
BatchSuccess::FetchTree(value)
}
BatchRequestKind::FetchInterface(request) => {
let value = json::fetch_interface_response_from_json(result)?;
value.validate_for(request)?;
BatchSuccess::FetchInterface(value)
}
BatchRequestKind::Invalid { .. } => {
return Err(CodecError::BatchInteractionMismatch { id });
}
}),
};
responses.push(BatchResponseItem { id, outcome });
}
let response = BatchResponse { responses };
correlate(request, &response, limits)?;
Ok(response)
}
/// Decodes a batch response, including item-local failures within HTTP 200.
pub fn decode_batch_response<B: AsRef<[u8]>>(
request: &BatchRequest,
value: &Response<B>,
limits: Limits,
) -> Result<DecodedResponse<BatchResponse>, ClientResponseError> {
let valid_content_type = value
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.is_some_and(is_json_content_type);
if !valid_content_type {
if value.status().is_success() {
return Err(ClientResponseError::invalid(
InvalidResponseKind::InvalidBatch,
"missing or non-UTF-8 application/json Content-Type",
));
}
return Err(response::transport_failure(value.status()));
}
let decoded = response::decode(
value.status(),
value.body().as_ref(),
ProtocolInteraction::Fetch,
limits,
|json| response_from_json(json, request, limits),
)
.map_err(|error| match error {
ClientResponseError::InvalidResponse { detail, .. } => {
ClientResponseError::invalid(InvalidResponseKind::InvalidBatch, detail)
}
other => other,
})?;
if let DecodedResponse::ProtocolFailure { error, .. } = &decoded
&& !matches!(
error.code,
ProtocolErrorCode::InvalidRequest
| ProtocolErrorCode::ResourceLimitExceeded
| ProtocolErrorCode::Internal
)
{
return Err(ClientResponseError::invalid(
InvalidResponseKind::InvalidBatch,
"protocol code is not valid for a top-level batch failure",
));
}
if let DecodedResponse::Success(success) = &decoded {
for item in &success.responses {
if let Ok(BatchSuccess::FetchInterface(interface)) = &item.outcome
&& interface.descriptor.format != INTERFACE_FORMAT_V1
{
return Err(ClientResponseError::UnsupportedDescriptorFormat {
format: interface.descriptor.format.clone(),
});
}
}
}
Ok(decoded)
}
fn object<'a>(value: &'a Json, field: &str) -> Result<&'a Map<String, Json>, CodecError> {
value.as_object().ok_or_else(|| CodecError::InvalidField {
field: field.into(),
reason: "expected object".into(),
})
}
fn exact_object<'a>(
value: &'a Json,
field: &str,
allowed: &[&str],
) -> Result<&'a Map<String, Json>, CodecError> {
let fields = object(value, field)?;
for name in fields.keys() {
if !allowed.contains(&name.as_str()) {
return Err(CodecError::UnknownField {
field: format!("{field}.{name}"),
});
}
}
Ok(fields)
}
fn required<'a>(fields: &'a Map<String, Json>, name: &str) -> Result<&'a Json, CodecError> {
fields
.get(name)
.ok_or_else(|| CodecError::MissingField { field: name.into() })
}
fn string(value: &Json, field: &str) -> Result<String, CodecError> {
value
.as_str()
.map(str::to_owned)
.ok_or_else(|| CodecError::InvalidField {
field: field.into(),
reason: "expected string".into(),
})
}
fn array<'a>(value: &'a Json, field: &str) -> Result<&'a [Json], CodecError> {
value
.as_array()
.map(Vec::as_slice)
.ok_or_else(|| CodecError::InvalidField {
field: field.into(),
reason: "expected array".into(),
})
}
crates/wip-https/src/codec.rs
+661
View File
@@ -0,0 +1,661 @@
use std::error::Error;
use std::fmt::{self, Display, Formatter};
use http::header::{ACCEPT, CONTENT_TYPE};
use http::{HeaderMap, Method, Request, Response, StatusCode};
use wip_protocol::{
CallOperationRequest, CallOperationResponse, FetchInterfaceRequest, FetchInterfaceResponse,
FetchRequest, FetchResponse, FetchTreeRequest, FetchTreeResponse, INTERFACE_FORMAT_V1,
InterfaceDescriptor, InterfaceTarget, ProtocolError, ProtocolInteraction, Target,
};
use crate::response::{self, DecodedResponse};
use crate::{
BodyKind, ClientResponseError, CodecError, Endpoint, InvalidResponseKind, JSON_CONTENT_TYPE,
Limits, ResourceLimitKind, Route, json,
};
fn request(
endpoint: &Endpoint,
route: Route,
body: Vec<u8>,
) -> Result<Request<Vec<u8>>, http::Error> {
Request::builder()
.method(Method::POST)
.uri(endpoint.route(route).as_str())
.header(CONTENT_TYPE, JSON_CONTENT_TYPE)
.header(ACCEPT, "application/json")
.body(body)
}
fn response(status: StatusCode, body: Vec<u8>) -> Result<Response<Vec<u8>>, http::Error> {
Response::builder()
.status(status)
.header(CONTENT_TYPE, JSON_CONTENT_TYPE)
.body(body)
}
fn require_response_content_type<B>(response: &Response<B>) -> Result<(), ClientResponseError> {
let valid = response
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.is_some_and(is_json_content_type);
if valid {
Ok(())
} else if response.status().is_success() {
Err(ClientResponseError::invalid(
InvalidResponseKind::InvalidSuccessBody,
"missing or non-UTF-8 application/json Content-Type",
))
} else {
Err(response::transport_failure(response.status()))
}
}
fn is_utf8_charset(value: &str) -> bool {
let value = value.trim();
value.eq_ignore_ascii_case("utf-8")
|| value
.strip_prefix('"')
.and_then(|value| value.strip_suffix('"'))
.is_some_and(|value| value.eq_ignore_ascii_case("utf-8"))
}
/// Returns whether a Content-Type value denotes UTF-8 `application/json`.
///
/// The charset parameter is optional because JSON exchanged by this binding is
/// always UTF-8; when present, its value must be `utf-8`. Other parameters are
/// rejected so intermediaries cannot silently select another representation.
#[must_use]
pub fn is_json_content_type(value: &str) -> bool {
let mut parts = value.split(';');
if !parts
.next()
.is_some_and(|media| media.trim().eq_ignore_ascii_case("application/json"))
{
return false;
}
let mut saw_charset = false;
for parameter in parts {
let Some((name, value)) = parameter.trim().split_once('=') else {
return false;
};
if !name.trim().eq_ignore_ascii_case("charset") || !is_utf8_charset(value) || saw_charset {
return false;
}
saw_charset = true;
}
true
}
fn accepts_json(headers: &HeaderMap) -> bool {
let mut present = false;
let mut best_match: Option<((u8, u8), f32)> = None;
for value in headers.get_all(ACCEPT) {
present = true;
let Ok(value) = value.to_str() else {
continue;
};
for range in value.split(',') {
let mut parts = range.split(';');
let media_range = parts.next().unwrap_or_default().trim();
let mut quality = 1.0_f32;
let mut saw_quality = false;
let mut saw_charset = false;
let mut media_parameter_count = 0;
let mut valid = true;
for parameter in parts {
let parameter = parameter.trim();
let (name, value) = parameter
.split_once('=')
.map_or((parameter, None), |(name, value)| {
(name.trim(), Some(value))
});
if name.is_empty() {
valid = false;
break;
}
if saw_quality {
// Parameters after q are Accept extensions and do not
// constrain the selected representation.
continue;
}
if name.eq_ignore_ascii_case("q") {
let Some(value) = value else {
valid = false;
break;
};
saw_quality = true;
match value.trim().parse::<f32>() {
Ok(value) if (0.0..=1.0).contains(&value) => quality = value,
_ => {
valid = false;
break;
}
}
} else {
let Some(value) = value else {
valid = false;
break;
};
if !name.eq_ignore_ascii_case("charset")
|| !is_utf8_charset(value)
|| saw_charset
{
valid = false;
break;
}
saw_charset = true;
media_parameter_count += 1;
}
}
let media_specificity = if media_range.eq_ignore_ascii_case("application/json") {
Some(2)
} else if media_range.eq_ignore_ascii_case("application/*") {
Some(1)
} else if media_range == "*/*" {
Some(0)
} else {
None
};
if valid && let Some(media_specificity) = media_specificity {
let specificity = (media_specificity, media_parameter_count);
match best_match {
Some((best_specificity, _)) if best_specificity > specificity => {}
Some((best_specificity, best_quality)) if best_specificity == specificity => {
best_match = Some((specificity, best_quality.max(quality)));
}
_ => best_match = Some((specificity, quality)),
}
}
}
}
if present {
best_match.is_some_and(|(_, quality)| quality > 0.0)
} else {
true
}
}
/// A failure while validating inbound HTTP request metadata.
#[derive(Debug)]
pub enum RequestMetadataError {
/// The method or route does not match the selected WIP interaction.
InvalidRequest(CodecError),
/// The request body does not use UTF-8 `application/json`.
UnsupportedMediaType,
/// The request's `Accept` metadata excludes `application/json`.
NotAcceptable,
}
impl RequestMetadataError {
/// Returns the HTTP status for this metadata failure.
#[must_use]
pub const fn status(&self) -> StatusCode {
match self {
Self::InvalidRequest(_) => StatusCode::BAD_REQUEST,
Self::UnsupportedMediaType => StatusCode::UNSUPPORTED_MEDIA_TYPE,
Self::NotAcceptable => StatusCode::NOT_ACCEPTABLE,
}
}
}
impl Display for RequestMetadataError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidRequest(error) => error.fmt(formatter),
Self::UnsupportedMediaType => {
formatter.write_str("expected UTF-8 application/json Content-Type")
}
Self::NotAcceptable => formatter.write_str("request does not accept application/json"),
}
}
}
impl Error for RequestMetadataError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::InvalidRequest(error) => Some(error),
Self::UnsupportedMediaType | Self::NotAcceptable => None,
}
}
}
/// Validates mandatory HTTP metadata for an inbound WIP request.
///
/// Both absolute-form and origin-form request URIs are accepted, but the path
/// must exactly equal the selected endpoint route and a query is forbidden.
/// Unsupported content negotiation is reported as a Transport Binding metadata
/// failure rather than a Core `invalid_request`.
pub fn validate_http_request<B>(
endpoint: &Endpoint,
route: Route,
value: &Request<B>,
) -> Result<(), RequestMetadataError> {
if value.method() != Method::POST {
return Err(RequestMetadataError::InvalidRequest(
CodecError::InvalidField {
field: "method".into(),
reason: "standard WIP routes require POST".into(),
},
));
}
let expected = endpoint.route(route);
if value.uri().path() != expected.path() || value.uri().query().is_some() {
return Err(RequestMetadataError::InvalidRequest(
CodecError::InvalidField {
field: "route".into(),
reason: "request URI does not match the selected standard route".into(),
},
));
}
let valid_content_type = value
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.is_some_and(is_json_content_type);
if !valid_content_type {
return Err(RequestMetadataError::UnsupportedMediaType);
}
if !accepts_json(value.headers()) {
return Err(RequestMetadataError::NotAcceptable);
}
Ok(())
}
/// Encodes a `fetch` HTTP request.
pub fn encode_fetch_request(
endpoint: &Endpoint,
value: &FetchRequest,
limits: Limits,
) -> Result<Request<Vec<u8>>, EncodeHttpError> {
value.validate().map_err(CodecError::from)?;
let body = json::serialize(
&json::fetch_request_to_json(value),
BodyKind::Request,
limits,
)?;
Ok(request(endpoint, Route::Fetch, body)?)
}
/// Decodes a `fetch` request body.
pub fn decode_fetch_request(body: &[u8], limits: Limits) -> Result<FetchRequest, CodecError> {
let value = json::parse(body, BodyKind::Request, limits)?;
json::fetch_request_from_json(&value)
}
/// Encodes a `fetch_tree` HTTP request.
pub fn encode_fetch_tree_request(
endpoint: &Endpoint,
value: &FetchTreeRequest,
limits: Limits,
) -> Result<Request<Vec<u8>>, EncodeHttpError> {
value.validate().map_err(CodecError::from)?;
let body = json::serialize(
&json::fetch_tree_request_to_json(value),
BodyKind::Request,
limits,
)?;
Ok(request(endpoint, Route::FetchTree, body)?)
}
/// Decodes a `fetch_tree` request body.
pub fn decode_fetch_tree_request(
body: &[u8],
limits: Limits,
) -> Result<FetchTreeRequest, CodecError> {
let value = json::parse(body, BodyKind::Request, limits)?;
json::fetch_tree_request_from_json(&value)
}
/// Encodes a `fetch_interface` HTTP request.
pub fn encode_fetch_interface_request(
endpoint: &Endpoint,
value: &FetchInterfaceRequest,
limits: Limits,
) -> Result<Request<Vec<u8>>, EncodeHttpError> {
let body = json::serialize(
&json::fetch_interface_request_to_json(value),
BodyKind::Request,
limits,
)?;
Ok(request(endpoint, Route::FetchInterface, body)?)
}
/// Decodes a `fetch_interface` request body.
pub fn decode_fetch_interface_request(
body: &[u8],
limits: Limits,
) -> Result<FetchInterfaceRequest, CodecError> {
let value = json::parse(body, BodyKind::Request, limits)?;
json::fetch_interface_request_from_json(&value)
}
/// Descriptor-independent fields needed to resolve a `call_operation` request.
///
/// A Host decodes this metadata first, fixes the current interface descriptor,
/// then passes the same body and descriptor to [`decode_call_operation_request`].
/// This preserves canonical path/interface/operation lookup and error precedence
/// without treating unvalidated argument JSON as a logical [`wip_protocol::Value`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CallOperationMetadata {
/// Path and optional object-state precondition.
pub target: Target,
/// Interface reference and optional interface precondition.
pub interface: InterfaceTarget,
/// Operation name used to select a declaration.
pub operation: String,
}
impl CallOperationMetadata {
/// Decodes the descriptor-bound request and verifies that routing metadata
/// still matches the values used to resolve `descriptor`.
pub fn decode_request(
&self,
body: &[u8],
descriptor: &InterfaceDescriptor,
limits: Limits,
) -> Result<CallOperationRequest, CodecError> {
let request = decode_call_operation_request(body, descriptor, limits)?;
if request.target != self.target
|| request.interface != self.interface
|| request.operation != self.operation
{
return Err(CodecError::InvalidField {
field: "request".into(),
reason: "call metadata changed after descriptor resolution".into(),
});
}
Ok(request)
}
}
/// Decodes descriptor-independent `call_operation` routing metadata.
pub fn decode_call_operation_metadata(
body: &[u8],
limits: Limits,
) -> Result<CallOperationMetadata, CodecError> {
let value = json::parse(body, BodyKind::Request, limits)?;
let (target, interface, operation) = json::call_request_metadata_from_json(&value)?;
Ok(CallOperationMetadata {
target,
interface,
operation,
})
}
/// Encodes a descriptor-bound `call_operation` HTTP request.
pub fn encode_call_operation_request(
endpoint: &Endpoint,
value: &CallOperationRequest,
descriptor: &InterfaceDescriptor,
limits: Limits,
) -> Result<Request<Vec<u8>>, EncodeHttpError> {
let value = json::call_request_to_json(value, descriptor)?;
let body = json::serialize(&value, BodyKind::Request, limits)?;
Ok(request(endpoint, Route::CallOperation, body)?)
}
/// Decodes a descriptor-bound `call_operation` request body.
pub fn decode_call_operation_request(
body: &[u8],
descriptor: &InterfaceDescriptor,
limits: Limits,
) -> Result<CallOperationRequest, CodecError> {
let value = json::parse(body, BodyKind::Request, limits)?;
json::call_request_from_json(&value, descriptor)
}
/// Encodes a successful `fetch` response as a direct body with HTTP 200.
pub fn encode_fetch_response(
request_value: &FetchRequest,
value: &FetchResponse,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
request_value
.validate_response(value)
.map_err(CodecError::from)?;
let body = json::serialize(&json::object_to_json(value), BodyKind::Response, limits)?;
Ok(response(StatusCode::OK, body)?)
}
/// Decodes and classifies a `fetch` client response.
pub fn decode_fetch_response<B: AsRef<[u8]>>(
request_value: &FetchRequest,
value: &Response<B>,
limits: Limits,
) -> Result<DecodedResponse<FetchResponse>, ClientResponseError> {
require_response_content_type(value)?;
response::decode(
value.status(),
value.body().as_ref(),
ProtocolInteraction::Fetch,
limits,
|json| {
let object = json::object_from_json(json, "response")?;
request_value.validate_response(&object)?;
Ok(object)
},
)
}
/// Encodes a successful `fetch_tree` response as a direct body with HTTP 200.
pub fn encode_fetch_tree_response(
request_value: &FetchTreeRequest,
value: &FetchTreeResponse,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
value
.validate_for(request_value)
.map_err(CodecError::from)?;
let body = json::serialize(
&json::fetch_tree_response_to_json(value),
BodyKind::Response,
limits,
)?;
Ok(response(StatusCode::OK, body)?)
}
/// Decodes and classifies a `fetch_tree` client response.
pub fn decode_fetch_tree_response<B: AsRef<[u8]>>(
request_value: &FetchTreeRequest,
value: &Response<B>,
limits: Limits,
) -> Result<DecodedResponse<FetchTreeResponse>, ClientResponseError> {
require_response_content_type(value)?;
response::decode(
value.status(),
value.body().as_ref(),
ProtocolInteraction::FetchTree,
limits,
|json| {
let tree = json::fetch_tree_response_from_json(json)?;
tree.validate_for(request_value)?;
Ok(tree)
},
)
}
/// Encodes a successful `fetch_interface` response as a direct body with HTTP 200.
pub fn encode_fetch_interface_response(
request_value: &FetchInterfaceRequest,
value: &FetchInterfaceResponse,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
value
.validate_for(request_value)
.map_err(CodecError::from)?;
let body = json::serialize(
&json::fetch_interface_response_to_json(value),
BodyKind::Response,
limits,
)?;
Ok(response(StatusCode::OK, body)?)
}
/// Decodes and classifies a `fetch_interface` client response.
pub fn decode_fetch_interface_response<B: AsRef<[u8]>>(
request_value: &FetchInterfaceRequest,
value: &Response<B>,
limits: Limits,
) -> Result<DecodedResponse<FetchInterfaceResponse>, ClientResponseError> {
require_response_content_type(value)?;
let decoded = response::decode(
value.status(),
value.body().as_ref(),
ProtocolInteraction::FetchInterface,
limits,
|json| {
let interface = json::fetch_interface_response_from_json(json)?;
interface.validate_for(request_value)?;
Ok(interface)
},
)?;
if let DecodedResponse::Success(success) = &decoded
&& success.descriptor.format != INTERFACE_FORMAT_V1
{
return Err(ClientResponseError::UnsupportedDescriptorFormat {
format: success.descriptor.format.clone(),
});
}
Ok(decoded)
}
/// Encodes a successful `call_operation` response as a direct body with HTTP 200.
pub fn encode_call_operation_response(
request_value: &CallOperationRequest,
descriptor: &InterfaceDescriptor,
value: &CallOperationResponse,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
let json = json::call_response_to_json(value, descriptor, &request_value.operation)?;
let body = json::serialize(&json, BodyKind::Response, limits)?;
Ok(response(StatusCode::OK, body)?)
}
/// Decodes and classifies a descriptor-bound `call_operation` client response.
pub fn decode_call_operation_response<B: AsRef<[u8]>>(
request_value: &CallOperationRequest,
descriptor: &InterfaceDescriptor,
value: &Response<B>,
limits: Limits,
) -> Result<DecodedResponse<CallOperationResponse>, ClientResponseError> {
require_response_content_type(value)?;
response::decode(
value.status(),
value.body().as_ref(),
ProtocolInteraction::CallOperation,
limits,
|json| json::call_response_from_json(json, descriptor, &request_value.operation),
)
}
fn validate_protocol_error(
interaction: ProtocolInteraction,
error: &ProtocolError,
) -> Result<(), CodecError> {
if !error.code.is_allowed_for(interaction) {
return Err(CodecError::InvalidField {
field: "error.code".into(),
reason: format!(
"code `{}` is not allowed for {interaction:?}",
response::error_code_name(error.code)
),
});
}
Ok(())
}
fn encode_protocol_error_with_status(
interaction: ProtocolInteraction,
error: &ProtocolError,
status: StatusCode,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
validate_protocol_error(interaction, error)?;
let body = json::serialize(&response::error_to_json(error), BodyKind::Response, limits)?;
Ok(response(status, body)?)
}
/// Encodes a canonical Host error envelope using its standard HTTP status.
///
/// The code must be allowed for `interaction`. This API accepts only
/// [`ProtocolError`], so client-local `InvalidResponse` and
/// `UnsupportedDescriptorFormat` classifications cannot be emitted as Host
/// error envelopes. Resource-limit errors use the logical-limit status; callers
/// that know the concrete limit class should use
/// [`encode_resource_limit_error_response`].
pub fn encode_protocol_error_response(
interaction: ProtocolInteraction,
error: &ProtocolError,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
encode_protocol_error_with_status(
interaction,
error,
response::status_for_error(error.code),
limits,
)
}
/// Encodes a `resource_limit_exceeded` envelope with its class-specific status.
pub fn encode_resource_limit_error_response(
interaction: ProtocolInteraction,
error: &ProtocolError,
kind: ResourceLimitKind,
limits: Limits,
) -> Result<Response<Vec<u8>>, EncodeHttpError> {
if error.code != wip_protocol::ProtocolErrorCode::ResourceLimitExceeded {
return Err(CodecError::InvalidField {
field: "error.code".into(),
reason: "resource-limit encoder requires resource_limit_exceeded".into(),
}
.into());
}
encode_protocol_error_with_status(
interaction,
error,
response::status_for_resource_limit(kind),
limits,
)
}
/// Failure while building an outbound framework-neutral HTTP message.
#[derive(Debug)]
pub enum EncodeHttpError {
/// JSON or protocol encoding failed.
Codec(CodecError),
/// The framework-neutral HTTP message builder rejected the URI or headers.
Http(http::Error),
}
impl std::fmt::Display for EncodeHttpError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Codec(error) => error.fmt(formatter),
Self::Http(error) => error.fmt(formatter),
}
}
}
impl std::error::Error for EncodeHttpError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Codec(error) => Some(error),
Self::Http(error) => Some(error),
}
}
}
impl From<CodecError> for EncodeHttpError {
fn from(value: CodecError) -> Self {
Self::Codec(value)
}
}
impl From<http::Error> for EncodeHttpError {
fn from(value: http::Error) -> Self {
Self::Http(value)
}
}
crates/wip-https/src/endpoint.rs
+156
View File
@@ -0,0 +1,156 @@
use std::error::Error;
use std::fmt::{self, Display, Formatter};
use url::Url;
/// The media type emitted for every WIP request and every response with a body.
pub const JSON_CONTENT_TYPE: &str = "application/json; charset=utf-8";
/// A fixed standard WIP over HTTPS v1 route.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Route {
/// Fetch one object.
Fetch,
/// Fetch a bounded object tree.
FetchTree,
/// Fetch an interface descriptor.
FetchInterface,
/// Call one operation.
CallOperation,
/// Package independent retrieval interactions.
Batch,
}
impl Route {
/// Returns the RFC 3986 relative reference used below an endpoint prefix.
#[must_use]
pub const fn relative_reference(self) -> &'static str {
match self {
Self::Fetch => "v1/fetch",
Self::FetchTree => "v1/fetch_tree",
Self::FetchInterface => "v1/fetch_interface",
Self::CallOperation => "v1/call_operation",
Self::Batch => "v1/batch",
}
}
}
/// A canonical absolute HTTPS base URL whose path always ends in `/`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Endpoint(Url);
impl Endpoint {
/// Parses and canonicalizes an endpoint.
///
/// The input must be an absolute HTTPS URL without a query or fragment. Its
/// path is an endpoint prefix, not a Worldspace path. A trailing slash is
/// appended when absent so RFC 3986 relative-reference resolution preserves
/// the final prefix segment.
pub fn parse(input: &str) -> Result<Self, EndpointError> {
let mut url = Url::parse(input).map_err(EndpointError::InvalidUrl)?;
if url.scheme() != "https" {
return Err(EndpointError::NotHttps);
}
if url.cannot_be_a_base() || url.host_str().is_none() {
return Err(EndpointError::NotAbsoluteBase);
}
if url.query().is_some() {
return Err(EndpointError::HasQuery);
}
if url.fragment().is_some() {
return Err(EndpointError::HasFragment);
}
if !url.path().ends_with('/') {
let path = format!("{}/", url.path());
url.set_path(&path);
}
Ok(Self(url))
}
/// Returns the canonical base URL.
#[must_use]
pub fn as_url(&self) -> &Url {
&self.0
}
/// Resolves one fixed v1 route below this endpoint prefix.
#[must_use]
pub fn route(&self, route: Route) -> Url {
self.0
.join(route.relative_reference())
.expect("fixed relative WIP routes are valid URL references")
}
/// Recognizes an exact standard route below this endpoint.
///
/// Query strings, fragments, additional path segments, and Worldspace paths
/// are not route components and therefore never match.
#[must_use]
pub fn recognize(&self, candidate: &Url) -> Option<Route> {
const ROUTES: [Route; 5] = [
Route::Fetch,
Route::FetchTree,
Route::FetchInterface,
Route::CallOperation,
Route::Batch,
];
if candidate.query().is_some() || candidate.fragment().is_some() {
return None;
}
ROUTES
.into_iter()
.find(|route| self.route(*route) == *candidate)
}
}
impl Display for Endpoint {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
self.0.fmt(formatter)
}
}
impl TryFrom<&str> for Endpoint {
type Error = EndpointError;
fn try_from(value: &str) -> Result<Self, Self::Error> {
Self::parse(value)
}
}
/// Why an endpoint is not a valid standard WIP HTTPS base.
#[derive(Debug)]
pub enum EndpointError {
/// URL parsing failed.
InvalidUrl(url::ParseError),
/// The URL scheme is not `https`.
NotHttps,
/// The URL is not a hierarchical absolute URL with an authority.
NotAbsoluteBase,
/// A query component was supplied.
HasQuery,
/// A fragment component was supplied.
HasFragment,
}
impl Display for EndpointError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidUrl(error) => write!(formatter, "invalid endpoint URL: {error}"),
Self::NotHttps => formatter.write_str("WIP endpoint must use HTTPS"),
Self::NotAbsoluteBase => {
formatter.write_str("WIP endpoint must be an absolute base URL")
}
Self::HasQuery => formatter.write_str("WIP endpoint must not contain a query"),
Self::HasFragment => formatter.write_str("WIP endpoint must not contain a fragment"),
}
}
}
impl Error for EndpointError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::InvalidUrl(error) => Some(error),
_ => None,
}
}
}
crates/wip-https/src/error.rs
+255
View File
@@ -0,0 +1,255 @@
use std::error::Error;
use std::fmt::{self, Display, Formatter};
/// Caller-selected hard limits applied before or while decoding JSON.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Limits {
/// Largest accepted request body in bytes.
pub(crate) max_request_bytes: usize,
/// Largest accepted response body in bytes.
pub(crate) max_response_bytes: usize,
/// Largest accepted JSON container nesting depth.
pub(crate) max_nesting: usize,
/// Largest accepted number of batch items.
pub(crate) max_batch_items: usize,
}
impl Limits {
/// Creates a nonzero limit set.
pub fn new(
max_request_bytes: usize,
max_response_bytes: usize,
max_nesting: usize,
max_batch_items: usize,
) -> Result<Self, LimitConfigurationError> {
if max_request_bytes == 0 {
return Err(LimitConfigurationError::ZeroRequestBytes);
}
if max_response_bytes == 0 {
return Err(LimitConfigurationError::ZeroResponseBytes);
}
if max_nesting == 0 {
return Err(LimitConfigurationError::ZeroNesting);
}
if max_batch_items == 0 {
return Err(LimitConfigurationError::ZeroBatchItems);
}
Ok(Self {
max_request_bytes,
max_response_bytes,
max_nesting,
max_batch_items,
})
}
/// Returns the request body byte limit.
#[must_use]
pub const fn max_request_bytes(self) -> usize {
self.max_request_bytes
}
/// Returns the response body byte limit.
#[must_use]
pub const fn max_response_bytes(self) -> usize {
self.max_response_bytes
}
/// Returns the JSON container nesting limit.
#[must_use]
pub const fn max_nesting(self) -> usize {
self.max_nesting
}
/// Returns the batch item count limit.
#[must_use]
pub const fn max_batch_items(self) -> usize {
self.max_batch_items
}
}
/// Why a [`Limits`] configuration is not bounded.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LimitConfigurationError {
/// Request-byte limit was zero.
ZeroRequestBytes,
/// Response-byte limit was zero.
ZeroResponseBytes,
/// Nesting limit was zero.
ZeroNesting,
/// Batch-item limit was zero.
ZeroBatchItems,
}
impl Display for LimitConfigurationError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::ZeroRequestBytes => "request byte limit must be nonzero",
Self::ZeroResponseBytes => "response byte limit must be nonzero",
Self::ZeroNesting => "nesting limit must be nonzero",
Self::ZeroBatchItems => "batch item limit must be nonzero",
})
}
}
impl Error for LimitConfigurationError {}
/// Whether a body is being decoded as a request or response.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BodyKind {
/// An inbound server request.
Request,
/// An inbound client response.
Response,
}
/// The class of a resource limit exceeded by a wire representation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResourceLimitKind {
/// A request or response representation exceeded its byte-size limit.
RepresentationBytes,
/// A logical limit such as nesting depth, batch count, or collection size was exceeded.
Logical,
}
/// A malformed or locally disallowed wire representation.
#[derive(Debug)]
pub enum CodecError {
/// The body exceeds its configured byte limit.
BodyTooLarge {
/// Actual body size.
actual: usize,
/// Configured maximum.
maximum: usize,
},
/// JSON syntax is invalid.
InvalidJson(serde_json::Error),
/// A JSON container exceeds the configured nesting depth.
NestingTooDeep {
/// Configured maximum.
maximum: usize,
},
/// A required field is absent.
MissingField {
/// Field name.
field: String,
},
/// An undeclared field is present.
UnknownField {
/// Field name.
field: String,
},
/// A field has an invalid JSON type or semantic representation.
InvalidField {
/// Field name or value location.
field: String,
/// Stable human-readable reason.
reason: String,
},
/// An optional field was represented by JSON null rather than omission.
NullOptionalField {
/// Field name.
field: String,
},
/// Base64 is not canonical RFC 4648 Section 4 encoding.
InvalidBase64 {
/// Field name or value location.
field: String,
},
/// Logical protocol validation rejected the decoded representation.
ProtocolValidation(wip_protocol::ValidationError),
/// The batch exceeds its configured item count.
TooManyBatchItems {
/// Actual item count.
actual: usize,
/// Configured maximum.
maximum: usize,
},
/// Batch item identifiers are not unique.
DuplicateBatchId {
/// Repeated identifier.
id: String,
},
/// A response contains a batch identifier that was not requested.
UnexpectedBatchId {
/// Unexpected identifier.
id: String,
},
/// A response omitted a requested batch identifier.
MissingBatchId {
/// Missing identifier.
id: String,
},
/// A batch item result does not match its requested interaction.
BatchInteractionMismatch {
/// Item identifier.
id: String,
},
}
impl CodecError {
/// Classifies this failure when it represents a canonical resource limit.
#[must_use]
pub const fn resource_limit_kind(&self) -> Option<ResourceLimitKind> {
match self {
Self::BodyTooLarge { .. } => Some(ResourceLimitKind::RepresentationBytes),
Self::NestingTooDeep { .. } | Self::TooManyBatchItems { .. } => {
Some(ResourceLimitKind::Logical)
}
_ => None,
}
}
}
impl Display for CodecError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::BodyTooLarge { actual, maximum } => {
write!(formatter, "body has {actual} bytes; maximum is {maximum}")
}
Self::InvalidJson(error) => write!(formatter, "invalid JSON: {error}"),
Self::NestingTooDeep { maximum } => {
write!(formatter, "JSON nesting exceeds maximum {maximum}")
}
Self::MissingField { field } => write!(formatter, "missing field `{field}`"),
Self::UnknownField { field } => write!(formatter, "unknown field `{field}`"),
Self::InvalidField { field, reason } => {
write!(formatter, "invalid field `{field}`: {reason}")
}
Self::NullOptionalField { field } => {
write!(
formatter,
"optional field `{field}` must be omitted instead of null"
)
}
Self::InvalidBase64 { field } => {
write!(formatter, "field `{field}` is not canonical base64")
}
Self::ProtocolValidation(error) => error.fmt(formatter),
Self::TooManyBatchItems { actual, maximum } => {
write!(formatter, "batch has {actual} items; maximum is {maximum}")
}
Self::DuplicateBatchId { id } => write!(formatter, "duplicate batch id `{id}`"),
Self::UnexpectedBatchId { id } => write!(formatter, "unexpected batch id `{id}`"),
Self::MissingBatchId { id } => write!(formatter, "missing batch id `{id}`"),
Self::BatchInteractionMismatch { id } => {
write!(formatter, "batch result does not match request `{id}`")
}
}
}
}
impl Error for CodecError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::InvalidJson(error) => Some(error),
Self::ProtocolValidation(error) => Some(error),
_ => None,
}
}
}
impl From<wip_protocol::ValidationError> for CodecError {
fn from(value: wip_protocol::ValidationError) -> Self {
Self::ProtocolValidation(value)
}
}
crates/wip-https/src/json.rs
+1305
View File
File diff suppressed because it is too large Load Diff
crates/wip-https/src/lib.rs
+67
View File
@@ -0,0 +1,67 @@
//! Framework-independent standard WIP over HTTPS v1 binding.
//!
//! This crate owns endpoint and route derivation, UTF-8 JSON encoding, canonical
//! success and error response handling, HTTP status mapping, descriptor-guided
//! operation-value conversion, and retrieval batching. It deliberately performs
//! no I/O and depends on no server framework, TLS implementation, filesystem
//! projection, client cache, or presentation layer.
//!
//! Logical values remain owned by [`wip_protocol`]. Validators and `Bytes` are
//! encoded in JSON bodies using canonical RFC 4648 Section 4 base64; this crate
//! does not infer WIP validator semantics from `ETag` or `If-Match`.
//!
//! ```
//! use wip_https::{Endpoint, Limits, encode_fetch_request};
//! use wip_protocol::FetchRequest;
//!
//! let endpoint = Endpoint::parse("https://example.test/api/wip")?;
//! let limits = Limits::new(64 * 1024, 1024 * 1024, 64, 100)?;
//! let request = encode_fetch_request(
//! &endpoint,
//! &FetchRequest { path: "/items/123".into() },
//! limits,
//! )?;
//! assert_eq!(request.uri(), "https://example.test/api/wip/v1/fetch");
//! assert_eq!(request.method(), http::Method::POST);
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
#![deny(missing_docs)]
mod batch;
mod codec;
mod endpoint;
mod error;
mod json;
mod response;
pub use batch::{
BatchMethod, BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse,
BatchResponseItem, BatchSuccess, decode_batch_request, decode_batch_response,
encode_batch_error_response, encode_batch_request, encode_batch_resource_limit_error_response,
encode_batch_response,
};
pub use codec::{
CallOperationMetadata, EncodeHttpError, RequestMetadataError, decode_call_operation_metadata,
decode_call_operation_request, decode_call_operation_response, decode_fetch_interface_request,
decode_fetch_interface_response, decode_fetch_request, decode_fetch_response,
decode_fetch_tree_request, decode_fetch_tree_response, encode_call_operation_request,
encode_call_operation_response, encode_fetch_interface_request,
encode_fetch_interface_response, encode_fetch_request, encode_fetch_response,
encode_fetch_tree_request, encode_fetch_tree_response, encode_protocol_error_response,
encode_resource_limit_error_response, is_json_content_type, validate_http_request,
};
pub use endpoint::{Endpoint, EndpointError, JSON_CONTENT_TYPE, Route};
pub use error::{BodyKind, CodecError, LimitConfigurationError, Limits, ResourceLimitKind};
pub use response::{
ClientResponseError, DecodedResponse, InvalidResponseKind, StatusMismatch,
TransportBindingFailure, TransportFailureKind, error_code_name, status_for_error,
status_for_resource_limit,
};
/// Framework-neutral HTTP types used by this binding's public API.
pub use http;
/// URL type used by [`Endpoint`].
pub use url;
/// Transport-independent logical protocol model used by this binding.
pub use wip_protocol;
crates/wip-https/src/response.rs
+365
View File
@@ -0,0 +1,365 @@
use std::error::Error;
use std::fmt::{self, Display, Formatter};
use http::StatusCode;
use serde_json::{Map, Value as Json};
use wip_protocol::{ProtocolError, ProtocolErrorCode, ProtocolInteraction};
use crate::{BodyKind, CodecError, Limits, ResourceLimitKind, json};
/// A successfully classified client response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DecodedResponse<T> {
/// A successful direct response body.
Success(T),
/// A canonical Host protocol failure.
ProtocolFailure {
/// The authoritative protocol error decoded from the envelope.
error: ProtocolError,
/// A diagnostic when the HTTP status differs from the canonical mapping.
status_mismatch: Option<StatusMismatch>,
},
}
/// Diagnostic evidence that HTTP metadata disagrees with a valid error envelope.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StatusMismatch {
/// Status received from the peer.
pub actual: StatusCode,
/// Canonical status for the envelope's protocol code.
pub expected: StatusCode,
}
/// Class of non-protocol HTTP failure returned without a valid WIP envelope.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransportFailureKind {
/// HTTP 401, commonly emitted by authentication infrastructure.
AuthenticationRequired,
/// HTTP 403, commonly emitted by endpoint policy or infrastructure.
EndpointForbidden,
/// Another non-success HTTP response without a WIP error envelope.
HttpStatus,
}
/// A non-success HTTP response that is not a valid WIP protocol failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransportBindingFailure {
/// HTTP status returned by the peer or intermediary.
pub status: StatusCode,
/// Coarse classification which does not invent a protocol error code.
pub kind: TransportFailureKind,
}
/// Why a response violates the WIP v1 response contract.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum InvalidResponseKind {
/// A 2xx response contained an error envelope.
ErrorEnvelopeOnSuccessStatus,
/// A non-2xx response contained a valid success body.
SuccessBodyOnErrorStatus,
/// A valid error envelope used a code forbidden for the interaction.
DisallowedProtocolCode,
/// A valid success body used a 2xx status other than canonical HTTP 200.
NonCanonicalSuccessStatus,
/// A 2xx body was malformed or semantically invalid.
InvalidSuccessBody,
/// A batch response did not correlate exactly with its request.
InvalidBatch,
}
/// A local failure while classifying or validating a peer response.
#[derive(Debug)]
pub enum ClientResponseError {
/// The HTTP exchange failed outside the protocol envelope.
TransportBinding(TransportBindingFailure),
/// The peer supplied a contradictory or invalid WIP response.
InvalidResponse {
/// Stable response-failure category.
kind: InvalidResponseKind,
/// Bounded diagnostic from local decoding.
detail: String,
},
/// The descriptor is structurally valid but uses an unsupported format.
UnsupportedDescriptorFormat {
/// Format identifier received from the Host.
format: String,
},
}
impl ClientResponseError {
pub(crate) fn invalid(kind: InvalidResponseKind, detail: impl Into<String>) -> Self {
Self::InvalidResponse {
kind,
detail: detail.into(),
}
}
}
impl Display for ClientResponseError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::TransportBinding(failure) => write!(
formatter,
"transport binding failure ({:?}, HTTP {})",
failure.kind, failure.status
),
Self::InvalidResponse { kind, detail } => {
write!(formatter, "invalid WIP response ({kind:?}): {detail}")
}
Self::UnsupportedDescriptorFormat { format } => {
write!(
formatter,
"unsupported interface descriptor format `{format}`"
)
}
}
}
}
impl Error for ClientResponseError {}
/// Returns the canonical HTTP status for a wire-level protocol error.
///
/// [`ProtocolErrorCode::ResourceLimitExceeded`] defaults to the logical-limit
/// status. Use [`status_for_resource_limit`] when the concrete limit class is
/// known.
#[must_use]
pub const fn status_for_error(code: ProtocolErrorCode) -> StatusCode {
match code {
ProtocolErrorCode::InvalidRequest => StatusCode::BAD_REQUEST,
ProtocolErrorCode::NotFound | ProtocolErrorCode::InterfaceNotFound => StatusCode::NOT_FOUND,
ProtocolErrorCode::InterfaceMismatch => StatusCode::CONFLICT,
ProtocolErrorCode::OperationNotFound => StatusCode::NOT_FOUND,
ProtocolErrorCode::InvalidArguments => StatusCode::UNPROCESSABLE_ENTITY,
ProtocolErrorCode::ValidatorRequired | ProtocolErrorCode::InterfaceValidatorRequired => {
StatusCode::PRECONDITION_REQUIRED
}
ProtocolErrorCode::ValidatorMismatch | ProtocolErrorCode::InterfaceValidatorMismatch => {
StatusCode::PRECONDITION_FAILED
}
ProtocolErrorCode::PermissionDenied => StatusCode::FORBIDDEN,
ProtocolErrorCode::ResourceLimitExceeded => StatusCode::UNPROCESSABLE_ENTITY,
ProtocolErrorCode::Internal | ProtocolErrorCode::OperationOutcomeUnknown => {
StatusCode::INTERNAL_SERVER_ERROR
}
}
}
/// Returns the canonical HTTP status for a concrete resource-limit class.
#[must_use]
pub const fn status_for_resource_limit(kind: ResourceLimitKind) -> StatusCode {
match kind {
ResourceLimitKind::RepresentationBytes => StatusCode::PAYLOAD_TOO_LARGE,
ResourceLimitKind::Logical => StatusCode::UNPROCESSABLE_ENTITY,
}
}
fn status_matches_error(status: StatusCode, code: ProtocolErrorCode) -> bool {
match code {
ProtocolErrorCode::ResourceLimitExceeded => {
status == StatusCode::PAYLOAD_TOO_LARGE || status == StatusCode::UNPROCESSABLE_ENTITY
}
_ => status == status_for_error(code),
}
}
/// Returns the stable snake-case wire spelling of a protocol code.
#[must_use]
pub const fn error_code_name(code: ProtocolErrorCode) -> &'static str {
match code {
ProtocolErrorCode::InvalidRequest => "invalid_request",
ProtocolErrorCode::NotFound => "not_found",
ProtocolErrorCode::InterfaceNotFound => "interface_not_found",
ProtocolErrorCode::InterfaceMismatch => "interface_mismatch",
ProtocolErrorCode::OperationNotFound => "operation_not_found",
ProtocolErrorCode::InvalidArguments => "invalid_arguments",
ProtocolErrorCode::ValidatorRequired => "validator_required",
ProtocolErrorCode::ValidatorMismatch => "validator_mismatch",
ProtocolErrorCode::InterfaceValidatorRequired => "interface_validator_required",
ProtocolErrorCode::InterfaceValidatorMismatch => "interface_validator_mismatch",
ProtocolErrorCode::PermissionDenied => "permission_denied",
ProtocolErrorCode::ResourceLimitExceeded => "resource_limit_exceeded",
ProtocolErrorCode::Internal => "internal",
ProtocolErrorCode::OperationOutcomeUnknown => "operation_outcome_unknown",
}
}
fn error_code_from_name(name: &str) -> Option<ProtocolErrorCode> {
Some(match name {
"invalid_request" => ProtocolErrorCode::InvalidRequest,
"not_found" => ProtocolErrorCode::NotFound,
"interface_not_found" => ProtocolErrorCode::InterfaceNotFound,
"interface_mismatch" => ProtocolErrorCode::InterfaceMismatch,
"operation_not_found" => ProtocolErrorCode::OperationNotFound,
"invalid_arguments" => ProtocolErrorCode::InvalidArguments,
"validator_required" => ProtocolErrorCode::ValidatorRequired,
"validator_mismatch" => ProtocolErrorCode::ValidatorMismatch,
"interface_validator_required" => ProtocolErrorCode::InterfaceValidatorRequired,
"interface_validator_mismatch" => ProtocolErrorCode::InterfaceValidatorMismatch,
"permission_denied" => ProtocolErrorCode::PermissionDenied,
"resource_limit_exceeded" => ProtocolErrorCode::ResourceLimitExceeded,
"internal" => ProtocolErrorCode::Internal,
"operation_outcome_unknown" => ProtocolErrorCode::OperationOutcomeUnknown,
_ => return None,
})
}
pub(crate) fn error_to_json(error: &ProtocolError) -> Json {
serde_json::json!({
"error": {
"code": error_code_name(error.code),
"message": error.message,
}
})
}
pub(crate) fn item_error_to_json(error: &ProtocolError) -> Json {
serde_json::json!({
"code": error_code_name(error.code),
"message": error.message,
})
}
pub(crate) fn item_error_from_json(value: &Json) -> Result<ProtocolError, CodecError> {
let fields = value
.as_object()
.ok_or_else(|| invalid_field("error", "expected object"))?;
exact(fields, &["code", "message"], "error")?;
let code_name = required_string(fields, "code")?;
let code = error_code_from_name(code_name)
.ok_or_else(|| invalid_field("error.code", "unknown protocol error code"))?;
let message = required_string(fields, "message")?.to_owned();
Ok(ProtocolError { code, message })
}
fn envelope_error_from_json(value: &Json) -> Result<Option<ProtocolError>, CodecError> {
let Some(fields) = value.as_object() else {
return Ok(None);
};
if fields.len() != 1 || !fields.contains_key("error") {
return Ok(None);
}
item_error_from_json(&fields["error"]).map(Some)
}
fn exact(fields: &Map<String, Json>, allowed: &[&str], parent: &str) -> Result<(), CodecError> {
for name in fields.keys() {
if !allowed.contains(&name.as_str()) {
return Err(CodecError::UnknownField {
field: format!("{parent}.{name}"),
});
}
}
for name in allowed {
if !fields.contains_key(*name) {
return Err(CodecError::MissingField {
field: format!("{parent}.{name}"),
});
}
}
Ok(())
}
fn required_string<'a>(fields: &'a Map<String, Json>, name: &str) -> Result<&'a str, CodecError> {
fields
.get(name)
.and_then(Json::as_str)
.ok_or_else(|| invalid_field(&format!("error.{name}"), "expected string"))
}
fn invalid_field(field: &str, reason: &str) -> CodecError {
CodecError::InvalidField {
field: field.into(),
reason: reason.into(),
}
}
pub(crate) fn decode<T>(
status: StatusCode,
body: &[u8],
interaction: ProtocolInteraction,
limits: Limits,
success: impl FnOnce(&Json) -> Result<T, CodecError>,
) -> Result<DecodedResponse<T>, ClientResponseError> {
let value = match json::parse(body, BodyKind::Response, limits) {
Ok(value) => value,
Err(_) if !status.is_success() => {
return Err(transport_failure(status));
}
Err(error) => {
return Err(ClientResponseError::invalid(
InvalidResponseKind::InvalidSuccessBody,
error.to_string(),
));
}
};
match envelope_error_from_json(&value) {
Ok(Some(error)) => {
if status.is_success() {
return Err(ClientResponseError::invalid(
InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
"protocol error envelope carried by a success status",
));
}
if !error.code.is_allowed_for(interaction) {
return Err(ClientResponseError::invalid(
InvalidResponseKind::DisallowedProtocolCode,
format!(
"code `{}` is not allowed for {interaction:?}",
error_code_name(error.code)
),
));
}
let expected = status_for_error(error.code);
let status_mismatch =
(!status_matches_error(status, error.code)).then_some(StatusMismatch {
actual: status,
expected,
});
Ok(DecodedResponse::ProtocolFailure {
error,
status_mismatch,
})
}
Err(_) if !status.is_success() => Err(transport_failure(status)),
Err(error) => Err(ClientResponseError::invalid(
InvalidResponseKind::InvalidSuccessBody,
error.to_string(),
)),
Ok(None) if status == StatusCode::OK => success(&value)
.map(DecodedResponse::Success)
.map_err(|error| {
ClientResponseError::invalid(
InvalidResponseKind::InvalidSuccessBody,
error.to_string(),
)
}),
Ok(None) if status.is_success() => match success(&value) {
Ok(_) => Err(ClientResponseError::invalid(
InvalidResponseKind::NonCanonicalSuccessStatus,
format!("success body carried by non-canonical HTTP {status}"),
)),
Err(error) => Err(ClientResponseError::invalid(
InvalidResponseKind::InvalidSuccessBody,
error.to_string(),
)),
},
Ok(None) => match success(&value) {
Ok(_) => Err(ClientResponseError::invalid(
InvalidResponseKind::SuccessBodyOnErrorStatus,
"valid success body carried by a non-success status",
)),
Err(_) => Err(transport_failure(status)),
},
}
}
pub(crate) fn transport_failure(status: StatusCode) -> ClientResponseError {
let kind = match status {
StatusCode::UNAUTHORIZED => TransportFailureKind::AuthenticationRequired,
StatusCode::FORBIDDEN => TransportFailureKind::EndpointForbidden,
_ => TransportFailureKind::HttpStatus,
};
ClientResponseError::TransportBinding(TransportBindingFailure { status, kind })
}
crates/wip-https/tests/batch.rs
+353
View File
@@ -0,0 +1,353 @@
use wip_https::http::StatusCode;
use wip_https::wip_protocol::{
FetchInterfaceRequest, FetchInterfaceResponse, FetchRequest, INTERFACE_FORMAT_V1,
InterfaceDescriptor, Object, ProtocolError, ProtocolErrorCode,
};
use wip_https::{
BatchMethod, BatchRequest, BatchRequestItem, BatchRequestKind, BatchResponse,
BatchResponseItem, BatchSuccess, ClientResponseError, DecodedResponse, Endpoint,
InvalidResponseKind, Limits, ResourceLimitKind, decode_batch_request, decode_batch_response,
encode_batch_error_response, encode_batch_request, encode_batch_resource_limit_error_response,
encode_batch_response,
};
fn limits() -> Limits {
Limits::new(100_000, 100_000, 64, 4).unwrap()
}
fn request() -> BatchRequest {
BatchRequest {
requests: vec![
BatchRequestItem {
id: "object".into(),
request: BatchRequestKind::Fetch(FetchRequest {
path: "/item".into(),
}),
},
BatchRequestItem {
id: "interface".into(),
request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
interface: "interface-v1".into(),
}),
},
],
}
}
#[test]
fn batch_round_trips_by_unique_id_with_item_failures_and_validators() {
let request = request();
let endpoint = Endpoint::parse("https://example.test/wip").unwrap();
let encoded_request = encode_batch_request(&endpoint, &request, limits()).unwrap();
assert_eq!(encoded_request.uri().path(), "/wip/v1/batch");
assert_eq!(encoded_request.headers()["accept"], "application/json");
assert_eq!(
decode_batch_request(encoded_request.body(), limits()).unwrap(),
request
);
let response = BatchResponse {
responses: vec![
BatchResponseItem {
id: "interface".into(),
outcome: Err(ProtocolError {
code: ProtocolErrorCode::InterfaceNotFound,
message: "gone".into(),
}),
},
BatchResponseItem {
id: "object".into(),
outcome: Ok(BatchSuccess::Fetch(Object {
name: "item".into(),
description: None,
interfaces: vec![],
r#ref: None,
validator: Some(vec![0, 1, 2, 255]),
})),
},
],
};
let encoded = encode_batch_response(&request, &response, limits()).unwrap();
assert_eq!(encoded.status(), StatusCode::OK);
assert!(
std::str::from_utf8(encoded.body())
.unwrap()
.contains("AAEC/w==")
);
assert_eq!(
decode_batch_response(&request, &encoded, limits()).unwrap(),
DecodedResponse::Success(response)
);
}
#[test]
fn batch_interface_validator_round_trips_in_item_body() {
let request = BatchRequest {
requests: vec![BatchRequestItem {
id: "interface".into(),
request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
interface: "interface-v1".into(),
}),
}],
};
let response = BatchResponse {
responses: vec![BatchResponseItem {
id: "interface".into(),
outcome: Ok(BatchSuccess::FetchInterface(FetchInterfaceResponse {
interface: "interface-v1".into(),
descriptor: InterfaceDescriptor {
format: INTERFACE_FORMAT_V1.into(),
documentation: None,
types: vec![],
operations: vec![],
},
validator: Some(vec![255, 254, 253]),
})),
}],
};
let encoded = encode_batch_response(&request, &response, limits()).unwrap();
assert!(
std::str::from_utf8(encoded.body())
.unwrap()
.contains("//79")
);
assert_eq!(
decode_batch_response(&request, &encoded, limits()).unwrap(),
DecodedResponse::Success(response)
);
}
#[test]
fn malformed_known_method_arguments_are_item_local() {
let body = br#"{
"requests": [
{"id":"valid","method":"fetch","arguments":{"path":"/item"}},
{"id":"invalid","method":"fetch_tree","arguments":{"path":"/","depth":"deep","limit":1}}
]
}"#;
let decoded = decode_batch_request(body, limits()).unwrap();
assert!(matches!(
decoded.requests[0].request,
BatchRequestKind::Fetch(_)
));
let invalid = match &decoded.requests[1].request {
BatchRequestKind::Invalid { method, error } => {
assert_eq!(*method, BatchMethod::FetchTree);
assert_eq!(error.code, ProtocolErrorCode::InvalidRequest);
error.clone()
}
other => panic!("expected item-local invalid request, got {other:?}"),
};
let response = BatchResponse {
responses: vec![
BatchResponseItem {
id: "valid".into(),
outcome: Ok(BatchSuccess::Fetch(Object {
name: "item".into(),
description: None,
interfaces: vec![],
r#ref: None,
validator: None,
})),
},
BatchResponseItem {
id: "invalid".into(),
outcome: Err(invalid),
},
],
};
let encoded = encode_batch_response(&decoded, &response, limits()).unwrap();
assert_eq!(encoded.status(), StatusCode::OK);
assert_eq!(
decode_batch_response(&decoded, &encoded, limits()).unwrap(),
DecodedResponse::Success(response)
);
}
#[test]
fn invalid_batch_envelopes_are_rejected_at_top_level() {
assert!(decode_batch_request(br#"{}"#, limits()).is_err());
let malformed_item = br#"{
"requests": [
{"id":"item","method":"fetch","arguments":{"path":"/"},"extra":true}
]
}"#;
assert!(decode_batch_request(malformed_item, limits()).is_err());
let duplicate = br#"{
"requests": [
{"id":"same","method":"fetch","arguments":{"path":"/a"}},
{"id":"same","method":"fetch","arguments":{"path":"/b"}}
]
}"#;
assert!(decode_batch_request(duplicate, limits()).is_err());
let operation = br#"{
"requests": [
{"id":"call","method":"call_operation","arguments":{}}
]
}"#;
assert!(decode_batch_request(operation, limits()).is_err());
let too_many = Limits::new(100_000, 100_000, 64, 1).unwrap();
assert!(decode_batch_request(duplicate, too_many).is_err());
}
#[test]
fn batch_resource_limits_use_413_or_422_and_never_429() {
let error = ProtocolError {
code: ProtocolErrorCode::ResourceLimitExceeded,
message: "bounded".into(),
};
for (kind, status) in [
(
ResourceLimitKind::RepresentationBytes,
StatusCode::PAYLOAD_TOO_LARGE,
),
(ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
] {
let encoded = encode_batch_resource_limit_error_response(&error, kind, limits()).unwrap();
assert_eq!(encoded.status(), status);
assert_ne!(encoded.status(), StatusCode::TOO_MANY_REQUESTS);
assert_eq!(
decode_batch_response(&request(), &encoded, limits()).unwrap(),
DecodedResponse::ProtocolFailure {
error: error.clone(),
status_mismatch: None,
}
);
}
}
#[test]
fn batch_success_body_requires_exactly_http_200() {
let request = request();
let response = BatchResponse {
responses: vec![
BatchResponseItem {
id: "object".into(),
outcome: Ok(BatchSuccess::Fetch(Object {
name: "item".into(),
description: None,
interfaces: vec![],
r#ref: None,
validator: None,
})),
},
BatchResponseItem {
id: "interface".into(),
outcome: Err(ProtocolError {
code: ProtocolErrorCode::InterfaceNotFound,
message: "gone".into(),
}),
},
],
};
let encoded = encode_batch_response(&request, &response, limits()).unwrap();
for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
let mut noncanonical = encoded.clone();
*noncanonical.status_mut() = status;
assert!(matches!(
decode_batch_response(&request, &noncanonical, limits()).unwrap_err(),
ClientResponseError::InvalidResponse { .. }
));
}
}
#[test]
fn top_level_batch_errors_use_the_batch_allowed_code_set() {
let invalid = ProtocolError {
code: ProtocolErrorCode::InvalidRequest,
message: "bad envelope".into(),
};
let encoded = encode_batch_error_response(&invalid, limits()).unwrap();
assert_eq!(
decode_batch_response(&request(), &encoded, limits()).unwrap(),
DecodedResponse::ProtocolFailure {
error: invalid,
status_mismatch: None,
}
);
let not_found = wip_https::http::Response::builder()
.status(StatusCode::NOT_FOUND)
.header("content-type", "application/json; charset=utf-8")
.body(br#"{"error":{"code":"not_found","message":"not a batch failure"}}"#.to_vec())
.unwrap();
assert!(matches!(
decode_batch_response(&request(), &not_found, limits()).unwrap_err(),
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::InvalidBatch,
..
}
));
}
#[test]
fn unsupported_batch_descriptor_waits_for_envelope_correlation() {
let duplicate = wip_https::http::Response::builder()
.status(StatusCode::OK)
.header("content-type", "application/json; charset=utf-8")
.body(
br#"{"responses":[{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future":true}}},{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"}}}]}"#
.to_vec(),
)
.unwrap();
assert!(matches!(
decode_batch_response(&request(), &duplicate, limits()).unwrap_err(),
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::InvalidBatch,
..
}
));
let missing = wip_https::http::Response::builder()
.status(StatusCode::OK)
.header("content-type", "application/json; charset=utf-8")
.body(
br#"{"responses":[{"id":"interface","result":{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"}}}]}"#
.to_vec(),
)
.unwrap();
assert!(matches!(
decode_batch_response(&request(), &missing, limits()).unwrap_err(),
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::InvalidBatch,
..
}
));
let request = BatchRequest {
requests: vec![BatchRequestItem {
id: "interface".into(),
request: BatchRequestKind::FetchInterface(FetchInterfaceRequest {
interface: "interface-v1".into(),
}),
}],
};
assert!(matches!(
decode_batch_response(&request, &missing, limits()).unwrap_err(),
ClientResponseError::UnsupportedDescriptorFormat { format }
if format == "wip-interface/2"
));
}
#[test]
fn batch_response_must_have_exactly_the_requested_ids() {
let request = request();
let missing = BatchResponse {
responses: vec![BatchResponseItem {
id: "object".into(),
outcome: Ok(BatchSuccess::Fetch(Object {
name: "item".into(),
description: None,
interfaces: vec![],
r#ref: None,
validator: None,
})),
}],
};
assert!(encode_batch_response(&request, &missing, limits()).is_err());
}
crates/wip-https/tests/codecs.rs
+508
View File
@@ -0,0 +1,508 @@
use std::collections::BTreeMap;
use wip_https::http::StatusCode;
use wip_https::wip_protocol::{
CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
FetchInterfaceResponse, FetchRequest, FetchTreeRequest, FetchTreeResponse, FieldDeclaration,
INTERFACE_FORMAT_V1, InterfaceDescriptor, InterfaceTarget, MAX_SAFE_INTEGER, Object,
ObjectTreeNode, OperationDeclaration, ParameterDeclaration, ReturnDeclaration, Target,
TypeDeclaration, TypeExpr, UnionCase, Value,
};
use wip_https::{
ClientResponseError, CodecError, DecodedResponse, Endpoint, InvalidResponseKind, Limits,
ResourceLimitKind, decode_call_operation_metadata, decode_call_operation_request,
decode_call_operation_response, decode_fetch_interface_request,
decode_fetch_interface_response, decode_fetch_request, decode_fetch_response,
decode_fetch_tree_request, decode_fetch_tree_response, encode_call_operation_request,
encode_call_operation_response, encode_fetch_interface_request,
encode_fetch_interface_response, encode_fetch_request, encode_fetch_response,
encode_fetch_tree_request, encode_fetch_tree_response,
};
fn limits() -> Limits {
Limits::new(1_000_000, 1_000_000, 100, 100).unwrap()
}
fn endpoint() -> Endpoint {
Endpoint::parse("https://example.test/wip").unwrap()
}
fn object(name: &str, validator: &[u8]) -> Object {
Object {
name: name.into(),
description: Some("description".into()),
interfaces: vec!["interface-v1".into()],
r#ref: Some(format!("object:{name}")),
validator: Some(validator.to_vec()),
}
}
fn descriptor() -> InterfaceDescriptor {
InterfaceDescriptor {
format: INTERFACE_FORMAT_V1.into(),
documentation: Some(Documentation {
summary: "Codec fixture".into(),
details: None,
}),
types: vec![TypeDeclaration {
name: "Pair".into(),
documentation: None,
definition: TypeExpr::Record {
fields: vec![
FieldDeclaration {
name: "required".into(),
required: true,
documentation: None,
r#type: TypeExpr::String,
},
FieldDeclaration {
name: "optional".into(),
required: false,
documentation: None,
r#type: TypeExpr::String,
},
FieldDeclaration {
name: "optional_json".into(),
required: false,
documentation: None,
r#type: TypeExpr::Json,
},
],
},
}],
operations: vec![OperationDeclaration {
name: "everything".into(),
documentation: None,
parameters: vec![
parameter("unit", TypeExpr::Unit),
parameter("boolean", TypeExpr::Boolean),
parameter("integer", TypeExpr::Integer),
parameter("number", TypeExpr::Number),
parameter("string", TypeExpr::String),
parameter("bytes", TypeExpr::Bytes),
parameter("entry", TypeExpr::Entry),
parameter(
"list",
TypeExpr::List {
items: Box::new(TypeExpr::Integer),
},
),
parameter(
"record",
TypeExpr::Named {
name: "Pair".into(),
},
),
parameter(
"enum",
TypeExpr::Enum {
cases: vec![EnumCase {
name: "ready".into(),
documentation: None,
}],
},
),
parameter(
"union",
TypeExpr::Union {
cases: vec![
UnionCase {
name: "empty".into(),
documentation: None,
payload: None,
},
UnionCase {
name: "found".into(),
documentation: None,
payload: Some(TypeExpr::Entry),
},
],
},
),
parameter("json", TypeExpr::Json),
],
returns: ReturnDeclaration {
documentation: None,
r#type: TypeExpr::Bytes,
},
}],
}
}
fn parameter(name: &str, r#type: TypeExpr) -> ParameterDeclaration {
ParameterDeclaration {
name: name.into(),
required: true,
documentation: None,
r#type,
}
}
fn record(fields: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
Value::Record(
fields
.into_iter()
.map(|(name, value)| (name.into(), value))
.collect(),
)
}
fn call_request() -> CallOperationRequest {
CallOperationRequest {
target: Target {
path: "/items/123".into(),
validator: Some(vec![0, 1, 2, 255]),
},
interface: InterfaceTarget {
reference: "interface-v1".into(),
validator: Some(vec![9, 8, 7]),
},
operation: "everything".into(),
arguments: BTreeMap::from([
("unit".into(), Value::Unit),
("boolean".into(), Value::Boolean(true)),
("integer".into(), Value::Integer(MAX_SAFE_INTEGER)),
("number".into(), Value::Number(1.5)),
("string".into(), Value::String("text".into())),
("bytes".into(), Value::Bytes(vec![0, 1, 2, 255])),
("entry".into(), Value::String("/items/123".into())),
(
"list".into(),
Value::List(vec![Value::Integer(1), Value::Integer(2)]),
),
(
"record".into(),
record([("required", Value::String("present".into()))]),
),
("enum".into(), Value::String("ready".into())),
(
"union".into(),
record([
("$case", Value::String("found".into())),
("value", Value::String("/items/123".into())),
]),
),
(
"json".into(),
record([
("null", Value::Unit),
("number", Value::Integer(2)),
("path_like", Value::String("/not-an-entry".into())),
]),
),
]),
}
}
#[test]
fn every_single_interaction_request_accepts_json() {
let fetch =
encode_fetch_request(&endpoint(), &FetchRequest { path: "/".into() }, limits()).unwrap();
let fetch_tree = encode_fetch_tree_request(
&endpoint(),
&FetchTreeRequest {
path: "/".into(),
depth: 1,
limit: 1,
},
limits(),
)
.unwrap();
let fetch_interface = encode_fetch_interface_request(
&endpoint(),
&FetchInterfaceRequest {
interface: "interface-v1".into(),
},
limits(),
)
.unwrap();
let call = encode_call_operation_request(&endpoint(), &call_request(), &descriptor(), limits())
.unwrap();
for request in [fetch, fetch_tree, fetch_interface, call] {
assert_eq!(request.headers()["accept"], "application/json");
}
}
#[test]
fn fetch_round_trips_direct_body_and_body_validator() {
let request = FetchRequest {
path: "/items/123".into(),
};
let encoded_request = encode_fetch_request(&endpoint(), &request, limits()).unwrap();
assert_eq!(encoded_request.uri().path(), "/wip/v1/fetch");
assert_eq!(
decode_fetch_request(encoded_request.body(), limits()).unwrap(),
request
);
let expected = object("123", &[0, 1, 2, 255]);
let encoded = encode_fetch_response(&request, &expected, limits()).unwrap();
assert_eq!(encoded.status(), StatusCode::OK);
assert_eq!(
decode_fetch_response(&request, &encoded, limits()).unwrap(),
DecodedResponse::Success(expected)
);
assert!(encoded.headers().get("etag").is_none());
}
#[test]
fn tree_and_interface_round_trip_nested_logical_models() {
let tree_request = FetchTreeRequest {
path: "/items".into(),
depth: 1,
limit: 2,
};
let encoded_request = encode_fetch_tree_request(&endpoint(), &tree_request, limits()).unwrap();
assert_eq!(
decode_fetch_tree_request(encoded_request.body(), limits()).unwrap(),
tree_request
);
let tree = FetchTreeResponse {
root: ObjectTreeNode {
object: object("items", b"root-validator"),
children: vec![ObjectTreeNode {
object: object("123", b"child-validator"),
children: vec![],
}],
},
truncated: false,
};
let encoded = encode_fetch_tree_response(&tree_request, &tree, limits()).unwrap();
assert_eq!(
decode_fetch_tree_response(&tree_request, &encoded, limits()).unwrap(),
DecodedResponse::Success(tree)
);
let interface_request = FetchInterfaceRequest {
interface: "interface-v1".into(),
};
let encoded_request =
encode_fetch_interface_request(&endpoint(), &interface_request, limits()).unwrap();
assert_eq!(
decode_fetch_interface_request(encoded_request.body(), limits()).unwrap(),
interface_request
);
let interface = FetchInterfaceResponse {
interface: interface_request.interface.clone(),
descriptor: descriptor(),
validator: Some(vec![4, 5, 6, 255]),
};
let encoded =
encode_fetch_interface_response(&interface_request, &interface, limits()).unwrap();
assert_eq!(
decode_fetch_interface_response(&interface_request, &encoded, limits()).unwrap(),
DecodedResponse::Success(interface)
);
}
#[test]
fn descriptor_guided_values_and_validators_round_trip_both_directions() {
let descriptor = descriptor();
let request = call_request();
let encoded =
encode_call_operation_request(&endpoint(), &request, &descriptor, limits()).unwrap();
let body = std::str::from_utf8(encoded.body()).unwrap();
assert!(body.contains("AAEC/w=="));
let metadata = decode_call_operation_metadata(encoded.body(), limits()).unwrap();
assert_eq!(metadata.target, request.target);
assert_eq!(metadata.interface, request.interface);
assert_eq!(metadata.operation, request.operation);
assert_eq!(
metadata
.decode_request(encoded.body(), &descriptor, limits())
.unwrap(),
request
);
let mut changed_route = request.clone();
changed_route.target.path = "/items/other".into();
let changed =
encode_call_operation_request(&endpoint(), &changed_route, &descriptor, limits()).unwrap();
assert!(
metadata
.decode_request(changed.body(), &descriptor, limits())
.is_err()
);
let mut null_json_request = request.clone();
null_json_request
.arguments
.insert("json".into(), Value::Unit);
null_json_request.arguments.insert(
"record".into(),
record([
("required", Value::String("present".into())),
("optional_json", Value::Unit),
]),
);
let null_json =
encode_call_operation_request(&endpoint(), &null_json_request, &descriptor, limits())
.unwrap();
assert_eq!(
decode_call_operation_request(null_json.body(), &descriptor, limits()).unwrap(),
null_json_request
);
let expected = CallOperationResponse {
result: Value::Bytes(vec![255, 0, 1]),
validator: Some(vec![3, 2, 1, 0]),
};
let encoded =
encode_call_operation_response(&request, &descriptor, &expected, limits()).unwrap();
assert!(
std::str::from_utf8(encoded.body())
.unwrap()
.contains("/wAB")
);
assert_eq!(
decode_call_operation_response(&request, &descriptor, &encoded, limits()).unwrap(),
DecodedResponse::Success(expected)
);
}
#[test]
fn malformed_unknown_null_and_noncanonical_base64_are_rejected() {
let limits = limits();
assert!(decode_fetch_request(br#"{"path":"/","extra":true}"#, limits).is_err());
assert!(decode_fetch_request(br#"{"path":"relative","path":"/"}"#, limits).is_err());
let request = call_request();
let descriptor = descriptor();
let body = serde_json::to_vec(&serde_json::json!({
"target": {"path": "/items/123", "validator": null},
"interface": {"reference": "interface-v1"},
"operation": "everything",
"arguments": {}
}))
.unwrap();
assert!(decode_call_operation_request(&body, &descriptor, limits).is_err());
let mut json: serde_json::Value = serde_json::from_slice(
encode_call_operation_request(&endpoint(), &request, &descriptor, limits)
.unwrap()
.body(),
)
.unwrap();
json["arguments"]["bytes"] = serde_json::Value::String("AAEC_w==".into());
assert!(
decode_call_operation_request(&serde_json::to_vec(&json).unwrap(), &descriptor, limits)
.is_err()
);
}
#[test]
fn caller_limits_bound_bytes_and_nesting() {
let tiny = Limits::new(8, 8, 2, 1).unwrap();
let too_large = decode_fetch_request(br#"{"path":"/long"}"#, tiny).unwrap_err();
assert!(matches!(&too_large, CodecError::BodyTooLarge { .. }));
assert_eq!(
too_large.resource_limit_kind(),
Some(ResourceLimitKind::RepresentationBytes)
);
let nested = br#"{"path":[[["/"]]]}"#;
let nesting_limited = Limits::new(1024, 1024, 2, 1).unwrap();
let too_deep = decode_fetch_request(nested, nesting_limited).unwrap_err();
assert!(matches!(&too_deep, CodecError::NestingTooDeep { .. }));
assert_eq!(
too_deep.resource_limit_kind(),
Some(ResourceLimitKind::Logical)
);
let outbound_limited = Limits::new(1_000_000, 1_000_000, 1, 10).unwrap();
assert!(
encode_call_operation_request(
&endpoint(),
&call_request(),
&descriptor(),
outbound_limited,
)
.is_err()
);
assert!(
encode_fetch_response(
&FetchRequest {
path: "/item".into(),
},
&object("item", b"validator"),
outbound_limited,
)
.is_err()
);
}
#[test]
fn unsupported_descriptor_format_is_client_local() {
let request = FetchInterfaceRequest {
interface: "interface-v1".into(),
};
let mut interface = FetchInterfaceResponse {
interface: request.interface.clone(),
descriptor: descriptor(),
validator: None,
};
interface.descriptor.format = "future-format".into();
let response = encode_fetch_interface_response(&request, &interface, limits()).unwrap();
let error = decode_fetch_interface_response(&request, &response, limits()).unwrap_err();
assert!(matches!(
error,
ClientResponseError::UnsupportedDescriptorFormat { .. }
));
let future_shape = wip_https::http::Response::builder()
.status(StatusCode::OK)
.header("content-type", "application/json; charset=utf-8")
.body(
br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2","future_shape":true}}"#
.to_vec(),
)
.unwrap();
assert!(matches!(
decode_fetch_interface_response(&request, &future_shape, limits()).unwrap_err(),
ClientResponseError::UnsupportedDescriptorFormat { format }
if format == "wip-interface/2"
));
for malformed in [
br#"{"interface":"wrong","descriptor":{"format":"wip-interface/2"}}"#.as_slice(),
br#"{"interface":"interface-v1","descriptor":{"format":"wip-interface/2"},"validator":null}"#
.as_slice(),
] {
let response = wip_https::http::Response::builder()
.status(StatusCode::OK)
.header("content-type", "application/json; charset=utf-8")
.body(malformed.to_vec())
.unwrap();
assert!(matches!(
decode_fetch_interface_response(&request, &response, limits()).unwrap_err(),
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::InvalidSuccessBody,
..
}
));
}
}
#[test]
fn invalid_success_is_classified_as_invalid_response() {
let response = wip_https::http::Response::builder()
.status(StatusCode::OK)
.header("content-type", "application/json; charset=utf-8")
.body(br#"{"name":"wrong","interfaces":[]}"#.to_vec())
.unwrap();
let error = decode_fetch_response(
&FetchRequest {
path: "/expected".into(),
},
&response,
limits(),
)
.unwrap_err();
assert!(matches!(
error,
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::InvalidSuccessBody,
..
}
));
}
crates/wip-https/tests/responses.rs
+304
View File
@@ -0,0 +1,304 @@
use wip_https::http::{Response, StatusCode};
use wip_https::wip_protocol::{
FetchRequest, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
};
use wip_https::{
ClientResponseError, DecodedResponse, InvalidResponseKind, Limits, ResourceLimitKind,
TransportFailureKind, decode_fetch_response, encode_protocol_error_response,
encode_resource_limit_error_response, error_code_name, is_json_content_type, status_for_error,
status_for_resource_limit,
};
fn limits() -> Limits {
Limits::new(64 * 1024, 64 * 1024, 32, 16).unwrap()
}
fn request() -> FetchRequest {
FetchRequest { path: "/".into() }
}
fn response(status: StatusCode, body: impl Into<Vec<u8>>) -> Response<Vec<u8>> {
Response::builder()
.status(status)
.header("content-type", "application/json; charset=utf-8")
.body(body.into())
.unwrap()
}
#[test]
fn content_type_accepts_only_utf8_json_syntax() {
assert!(is_json_content_type("application/json"));
assert!(is_json_content_type("Application/JSON; Charset=\"UTF-8\""));
assert!(!is_json_content_type("application/json; charset=utf-16"));
assert!(!is_json_content_type("application/json; charset=\"utf-8"));
assert!(!is_json_content_type("application/json; charset=utf-8\""));
assert!(!is_json_content_type("application/json; profile=other"));
}
#[test]
fn every_protocol_code_has_stable_name_and_status() {
let expected = [
(
ProtocolErrorCode::InvalidRequest,
"invalid_request",
StatusCode::BAD_REQUEST,
),
(
ProtocolErrorCode::NotFound,
"not_found",
StatusCode::NOT_FOUND,
),
(
ProtocolErrorCode::InterfaceNotFound,
"interface_not_found",
StatusCode::NOT_FOUND,
),
(
ProtocolErrorCode::InterfaceMismatch,
"interface_mismatch",
StatusCode::CONFLICT,
),
(
ProtocolErrorCode::OperationNotFound,
"operation_not_found",
StatusCode::NOT_FOUND,
),
(
ProtocolErrorCode::InvalidArguments,
"invalid_arguments",
StatusCode::UNPROCESSABLE_ENTITY,
),
(
ProtocolErrorCode::ValidatorRequired,
"validator_required",
StatusCode::PRECONDITION_REQUIRED,
),
(
ProtocolErrorCode::ValidatorMismatch,
"validator_mismatch",
StatusCode::PRECONDITION_FAILED,
),
(
ProtocolErrorCode::InterfaceValidatorRequired,
"interface_validator_required",
StatusCode::PRECONDITION_REQUIRED,
),
(
ProtocolErrorCode::InterfaceValidatorMismatch,
"interface_validator_mismatch",
StatusCode::PRECONDITION_FAILED,
),
(
ProtocolErrorCode::PermissionDenied,
"permission_denied",
StatusCode::FORBIDDEN,
),
(
ProtocolErrorCode::ResourceLimitExceeded,
"resource_limit_exceeded",
StatusCode::UNPROCESSABLE_ENTITY,
),
(
ProtocolErrorCode::Internal,
"internal",
StatusCode::INTERNAL_SERVER_ERROR,
),
(
ProtocolErrorCode::OperationOutcomeUnknown,
"operation_outcome_unknown",
StatusCode::INTERNAL_SERVER_ERROR,
),
];
assert_eq!(expected.len(), ProtocolErrorCode::ALL.len());
for (code, name, status) in expected {
assert_eq!(error_code_name(code), name);
assert_eq!(status_for_error(code), status);
}
}
#[test]
fn resource_limit_statuses_encode_and_decode_by_concrete_limit_class() {
let error = ProtocolError {
code: ProtocolErrorCode::ResourceLimitExceeded,
message: "bounded".into(),
};
let cases = [
(
ResourceLimitKind::RepresentationBytes,
StatusCode::PAYLOAD_TOO_LARGE,
),
(ResourceLimitKind::Logical, StatusCode::UNPROCESSABLE_ENTITY),
];
for (kind, status) in cases {
assert_eq!(status_for_resource_limit(kind), status);
let encoded = encode_resource_limit_error_response(
ProtocolInteraction::Fetch,
&error,
kind,
limits(),
)
.unwrap();
assert_eq!(encoded.status(), status);
assert_eq!(
decode_fetch_response(&request(), &encoded, limits()).unwrap(),
DecodedResponse::ProtocolFailure {
error: error.clone(),
status_mismatch: None,
}
);
}
let default =
encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
assert_eq!(default.status(), StatusCode::UNPROCESSABLE_ENTITY);
assert_ne!(default.status(), StatusCode::TOO_MANY_REQUESTS);
}
#[test]
fn rate_limit_status_without_protocol_envelope_stays_transport_failure() {
let response = Response::builder()
.status(StatusCode::TOO_MANY_REQUESTS)
.body(b"rate limited".to_vec())
.unwrap();
assert!(matches!(
decode_fetch_response(&request(), &response, limits()).unwrap_err(),
ClientResponseError::TransportBinding(failure)
if failure.status == StatusCode::TOO_MANY_REQUESTS
&& failure.kind == TransportFailureKind::HttpStatus
));
}
#[test]
fn valid_success_body_requires_exactly_http_200() {
let success_body = br#"{"name":"","interfaces":[]}"#;
for status in [StatusCode::CREATED, StatusCode::ACCEPTED] {
assert!(matches!(
decode_fetch_response(&request(), &response(status, success_body), limits())
.unwrap_err(),
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::NonCanonicalSuccessStatus,
..
}
));
}
}
#[test]
fn server_encoder_rejects_codes_disallowed_for_the_interaction() {
let error = ProtocolError {
code: ProtocolErrorCode::InterfaceNotFound,
message: "not valid for fetch".into(),
};
assert!(encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).is_err());
}
#[test]
fn valid_envelope_code_is_authoritative_when_status_mismatches() {
let error = ProtocolError {
code: ProtocolErrorCode::NotFound,
message: "missing".into(),
};
let mut encoded =
encode_protocol_error_response(ProtocolInteraction::Fetch, &error, limits()).unwrap();
*encoded.status_mut() = StatusCode::IM_A_TEAPOT;
assert_eq!(
decode_fetch_response(&request(), &encoded, limits()).unwrap(),
DecodedResponse::ProtocolFailure {
error,
status_mismatch: Some(wip_https::StatusMismatch {
actual: StatusCode::IM_A_TEAPOT,
expected: StatusCode::NOT_FOUND,
}),
}
);
}
#[test]
fn envelope_and_status_contradictions_are_invalid_responses() {
let error_body = br#"{"error":{"code":"not_found","message":"missing"}}"#;
let on_success =
decode_fetch_response(&request(), &response(StatusCode::OK, error_body), limits())
.unwrap_err();
assert!(matches!(
on_success,
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::ErrorEnvelopeOnSuccessStatus,
..
}
));
let success_body = br#"{"name":"","interfaces":[]}"#;
let on_error = decode_fetch_response(
&request(),
&response(StatusCode::BAD_GATEWAY, success_body),
limits(),
)
.unwrap_err();
assert!(matches!(
on_error,
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::SuccessBodyOnErrorStatus,
..
}
));
}
#[test]
fn disallowed_protocol_code_is_invalid_instead_of_reclassified() {
let body = br#"{"error":{"code":"interface_not_found","message":"wrong interaction"}}"#;
let error = decode_fetch_response(&request(), &response(StatusCode::NOT_FOUND, body), limits())
.unwrap_err();
assert!(matches!(
error,
ClientResponseError::InvalidResponse {
kind: InvalidResponseKind::DisallowedProtocolCode,
..
}
));
}
#[test]
fn proxy_authentication_and_endpoint_failures_stay_transport_failures() {
let cases = [
(
StatusCode::BAD_GATEWAY,
TransportFailureKind::HttpStatus,
b"proxy failure".as_slice(),
),
(
StatusCode::UNAUTHORIZED,
TransportFailureKind::AuthenticationRequired,
b"login required".as_slice(),
),
(
StatusCode::FORBIDDEN,
TransportFailureKind::EndpointForbidden,
b"denied".as_slice(),
),
];
for (status, expected_kind, body) in cases {
let response = Response::builder()
.status(status)
.body(body.to_vec())
.unwrap();
let error = decode_fetch_response(&request(), &response, limits()).unwrap_err();
assert!(matches!(
error,
ClientResponseError::TransportBinding(failure)
if failure.status == status && failure.kind == expected_kind
));
}
}
#[test]
fn malformed_non_success_envelope_is_transport_binding_failure() {
let malformed = response(
StatusCode::BAD_GATEWAY,
br#"{"error":{"code":"not_found","message":null}}"#,
);
assert!(matches!(
decode_fetch_response(&request(), &malformed, limits()).unwrap_err(),
ClientResponseError::TransportBinding(_)
));
}
crates/wip-https/tests/routes.rs
+127
View File
@@ -0,0 +1,127 @@
use wip_https::http::{Method, Request, StatusCode};
use wip_https::{Endpoint, RequestMetadataError, Route, validate_http_request};
#[test]
fn endpoint_is_https_absolute_queryless_and_canonical() {
let endpoint = Endpoint::parse("https://example.test/root/prefix").unwrap();
assert_eq!(endpoint.to_string(), "https://example.test/root/prefix/");
let expected = [
(Route::Fetch, "https://example.test/root/prefix/v1/fetch"),
(
Route::FetchTree,
"https://example.test/root/prefix/v1/fetch_tree",
),
(
Route::FetchInterface,
"https://example.test/root/prefix/v1/fetch_interface",
),
(
Route::CallOperation,
"https://example.test/root/prefix/v1/call_operation",
),
(Route::Batch, "https://example.test/root/prefix/v1/batch"),
];
for (route, url) in expected {
assert_eq!(endpoint.route(route).as_str(), url);
assert_eq!(
endpoint.recognize(&wip_https::url::Url::parse(url).unwrap()),
Some(route)
);
}
assert_eq!(
endpoint.recognize(
&wip_https::url::Url::parse("https://example.test/root/prefix/v1/fetch?path=/items")
.unwrap()
),
None
);
}
#[test]
fn routes_never_mix_worldspace_paths_into_endpoint_prefixes() {
let endpoint = Endpoint::parse("https://example.test/wip/%E4%B8%96%E7%95%8C/").unwrap();
let route = endpoint.route(Route::Fetch);
assert_eq!(route.path(), "/wip/%E4%B8%96%E7%95%8C/v1/fetch");
assert!(!route.as_str().contains("items"));
}
#[test]
fn inbound_http_metadata_enforces_post_route_and_json() {
let endpoint = Endpoint::parse("https://example.test/wip").unwrap();
let valid = Request::builder()
.method(Method::POST)
.uri("/wip/v1/fetch")
.header("content-type", "application/json; charset=utf-8")
.body(Vec::<u8>::new())
.unwrap();
assert!(validate_http_request(&endpoint, Route::Fetch, &valid).is_ok());
let wrong_method = Request::builder()
.method(Method::GET)
.uri("/wip/v1/fetch")
.header("content-type", "application/json")
.body(Vec::<u8>::new())
.unwrap();
assert!(validate_http_request(&endpoint, Route::Fetch, &wrong_method).is_err());
let wrong_route = Request::builder()
.method(Method::POST)
.uri("/wip/v1/fetch_tree")
.header("content-type", "application/json")
.body(Vec::<u8>::new())
.unwrap();
assert!(validate_http_request(&endpoint, Route::Fetch, &wrong_route).is_err());
for accept in [
"text/plain, */*;q=1, application/json;q=0",
"application/json; charset=utf-16",
"application/json; profile=future",
] {
let incompatible_accept = Request::builder()
.method(Method::POST)
.uri("/wip/v1/fetch")
.header("content-type", "application/json")
.header("accept", accept)
.body(Vec::<u8>::new())
.unwrap();
let error =
validate_http_request(&endpoint, Route::Fetch, &incompatible_accept).unwrap_err();
assert!(matches!(&error, RequestMetadataError::NotAcceptable));
assert_eq!(error.status(), StatusCode::NOT_ACCEPTABLE);
}
for accept in [
"application/json; charset=UTF-8",
"application/json; q=1; profile=accept-extension",
] {
let compatible_accept = Request::builder()
.method(Method::POST)
.uri("/wip/v1/fetch")
.header("content-type", "application/json")
.header("accept", accept)
.body(Vec::<u8>::new())
.unwrap();
assert!(validate_http_request(&endpoint, Route::Fetch, &compatible_accept).is_ok());
}
let unsupported_media_type = Request::builder()
.method(Method::POST)
.uri("/wip/v1/fetch")
.header("content-type", "text/plain")
.header("accept", "application/json")
.body(Vec::<u8>::new())
.unwrap();
let error =
validate_http_request(&endpoint, Route::Fetch, &unsupported_media_type).unwrap_err();
assert!(matches!(&error, RequestMetadataError::UnsupportedMediaType));
assert_eq!(error.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
}
#[test]
fn invalid_endpoint_components_are_rejected() {
assert!(Endpoint::parse("http://example.test/wip").is_err());
assert!(Endpoint::parse("/relative").is_err());
assert!(Endpoint::parse("https://example.test/wip?q=1").is_err());
assert!(Endpoint::parse("https://example.test/wip#fragment").is_err());
}