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-4-end-to-end-public-api
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
16 Commits
work/T-4-end-to-end-public-api ... 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
Hare 6de58da17d feat: model operation outcome guarantees 2026-09-30 05:52:38 +09:00
Hare 027555eb4e fix: align protocol error semantics 2026-09-30 05:26:34 +09:00
Hare 75119f23e5 feat(example): restore virtual workspace conformance 2026-09-29 06:51:05 +09:00
Hare 653a1171a2 fix: reject malformed host target paths 2026-09-29 06:35:10 +09:00
Hare 2efda433e7 fix: align host dispatch with canonical paths 2026-09-29 06:28:33 +09:00
Hare 2d524723a4 fix: align interface macros with canonical values 2026-09-29 06:11:07 +09:00
Hare 7f4e0e4460 fix: integrate canonical protocol model 2026-09-29 05:54:36 +09:00
Hare 4f0552c48f fix: align protocol model with canonical WIP 2026-09-29 05:47:14 +09:00
45 changed files with 13131 additions and 2763 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"
Cargo.toml
+1 -20
View File
@@ -1,22 +1,3 @@
[workspace]
members = [
".",
"crates/wip-host",
"crates/wip-interface",
"crates/wip-interface-macros",
"crates/wip-protocol",
]
members = ["crates/*"]
resolver = "3"
[package]
name = "wip-public-api-example"
version = "0.1.0"
edition = "2024"
description = "End-to-end example of the public WIP Rust APIs"
license = "MIT OR Apache-2.0"
publish = false
[dependencies]
wip-host = { path = "crates/wip-host" }
wip-interface = { path = "crates/wip-interface" }
wip-protocol = { path = "crates/wip-protocol" }
README.md
+132 -47
View File
@@ -2,15 +2,25 @@
Rust building blocks for the Web Interface Protocol (WIP).
The repository currently provides a transport-independent protocol model, a
Rust interface-authoring facade, and a request-scoped host runtime. HTTP and
other transport bindings are intentionally outside the supported slice.
The repository is a resolver-3 virtual Cargo workspace whose packages all live
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
@@ -22,32 +32,42 @@ 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 `OperationCall`/`OperationResult`
without placing transport-specific types in descriptors or application traits.
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.
## End-to-end example
[`src/lib.rs`](src/lib.rs) is the complete public-API example and
[`src/main.rs`](src/main.rs) runs it. It demonstrates all of the following:
[`crates/wip-public-api-example/src/lib.rs`](crates/wip-public-api-example/src/lib.rs)
is the complete public-API example and
[`crates/wip-public-api-example/src/main.rs`](crates/wip-public-api-example/src/main.rs)
runs it. It demonstrates all of the following:
1. public application DTOs derived as `WipType` records and unions;
1. public application DTOs derived as `WipType` records, enums, and unions,
including canonical entry paths and schema-opaque JSON;
2. two public traits declared with `#[wip::interface]`;
3. a private host struct implementing both traits;
4. explicit publication of both interfaces on one object;
5. registry observation and validation of generated descriptors;
6. calls made with interface references, operation names, and `Value` arguments;
4. explicit publication of both interfaces as an ordered set on one object;
5. separate observation of opaque interface references, descriptors, and
descriptor validators;
6. calls qualified by `target.path`, object validator, interface reference and
validator, operation, and schema-neutral `Value` arguments;
7. validated result values decoded back to the typed application result;
8. independent dispatch of the same `status` operation name on both interfaces;
9. a domain rejection returned as data and a backend failure returned as a host
error.
9. distinct domain rejection, rollback-confirmed and outcome-unknown
host/backend failures, `PermissionDenied`, stale validator recovery, interface
membership, and lookup failure codes; and
10. canonical failure precedence when several request fields are invalid.
Run it inside the development shell:
@@ -56,10 +76,17 @@ nix develop
cargo run --package wip-public-api-example
```
The normal integration test is in [`tests/end_to_end.rs`](tests/end_to_end.rs).
Unit tests beside the example additionally cover every host dispatch failure,
invalid arguments and results, interface membership, validators, and
same-named operations.
The public-only conformance suite is in
[`crates/wip-public-api-example/tests/end_to_end.rs`](crates/wip-public-api-example/tests/end_to_end.rs).
It covers canonical object/descriptor shape, ordered interfaces,
schema-neutral record/enum/union/entry/JSON values, fully qualified calls, and
the distinct domain, host, authorization, validator-recovery, and interface
failure classes. Exhaustive public type construction and matching make legacy
ObjectId, descriptor `name`, and semantic `Value` variants compile-time
regressions. Unit tests in the public crates additionally cover every host
dispatch failure, `InvalidRequest` versus descriptor-bound `InvalidArguments`,
invalid local responses, validators, same-named operations, and exhaustive
per-interaction protocol error-code sets.
## Interface authoring
@@ -104,12 +131,13 @@ A supported interface is a public, non-generic trait containing methods with:
- `()` only as the application return when no value is produced; and
- direct `Option<T>` only for an omittable parameter.
`WipType` derives support named-field structs, all-unit enums, and enums whose
variants each contain exactly one unnamed payload. The macros reject private,
`WipType` derives support named-field structs, all-unit enums, and unions whose
cases may be unit variants or variants containing exactly one unnamed payload.
The macros reject private,
generic, inherited, unsafe, auto, or associated-item traits; const, async,
unsafe, extern, variadic, generic, default-bodied, or non-`&self` methods;
borrowed/custom-lifetime values; tuple/unit/generic structs; Rust unions;
mixed/named-field enum variants; explicit discriminants; nested `Option`; and
named-field/multi-field enum variants; explicit discriminants; nested `Option`; and
`Option` in returns, collections, entries, or union payloads. These diagnostics
are compile-fail tested under `crates/wip-interface/tests/ui`.
@@ -117,23 +145,36 @@ are compile-fail tested under `crates/wip-interface/tests/ui`.
| Rust | Protocol |
| --- | --- |
| `()` as an operation result | no returned value |
| `()` | unit / `Value::Unit` |
| `bool` | boolean |
| integer primitives | JavaScript-lossless integer |
| `f32`, `f64` | finite number |
| `String` | string |
| `wip::Bytes` | bytes |
| `wip::JsonValue` | JSON |
| `wip::Entry<K, V>` | entry |
| `wip::JsonValue` | JSON interpreted over the schema-neutral `Value` tree |
| `wip::Entry` | canonical absolute Worldspace path encoded as a string |
| `Vec<T>` | list |
| named-field `#[derive(wip::WipType)]` struct | named record |
| all-unit `#[derive(wip::WipType)]` enum | named enum |
| all-newtype `#[derive(wip::WipType)]` enum | named tagged union |
| all-unit `#[derive(wip::WipType)]` enum | named enum encoded as a string |
| mixed unit/newtype or all-newtype enum | named union encoded as a discriminator record |
`Option<T>` means that a direct DTO field or operation parameter may be
omitted; it is not protocol null. JSON null remains available inside
`wip::JsonValue`.
#### Migration from the pre-canonical value API
The old generic `wip::Entry<K, V>` represented an application key/value pair
and is no longer available. Use `wip::Entry::new("/canonical/path")` for a
Worldspace entry path and place any associated application data in a record.
`Entry` encodes as `Value::String` and validates the canonical absolute path.
The semantic `Value::Json`, `Value::Entry`, `Value::Enum`, and `Value::Union`
variants have also been removed. JSON recursively uses `Unit`, primitive,
`List`, and `Record` values and rejects `Bytes`; enums use `String`; unions use
a `Record` containing `$case` and, for payload-bearing cases, `value`. Unit
operation results are represented explicitly as `Value::Unit`.
Rust doc comments become descriptor metadata. For an operation, a `# Returns`
section documents the return declaration; text before that section documents
the operation itself.
@@ -155,25 +196,65 @@ let protocol_object = published.protocol_object();
`expose` compiles only when the object implements the generated definition's
interface trait. Implementing a trait does not expose it automatically, empty
interface sets are valid, insertion order is preserved, and duplicate
references are rejected. Registry references are opaque; descriptor names and
Rust type names are not used as independent wire identity.
references are rejected. Registry references are opaque and remain outside the
descriptor; generated descriptors contain neither those references nor Rust
trait identity.
Dispatch is qualified by interface reference and operation name. The host
checks current object identity and validator policy, current interface
membership, interface validator, descriptor operation, arguments, and result
while retaining the selected object and registered artifact. Host-private
fields and backend handles are never projected by `WipObject`.
Dispatch is qualified by interface reference and operation name and targets a
canonical Worldspace path. An `ObjectProvider` validates that path before
resolution, maps malformed paths to `InvalidRequest`, then resolves a valid path
exactly once inside `with_object`; the host checks the supplied object validator,
current interface membership, interface validator, descriptor operation,
operation-specific object-validator policy, arguments, and authorization in
canonical precedence. Path and children remain provider resolution context and
are never projected by `WipObject`; host-private fields and backend handles are
also excluded.
Application domain failures belong in a derived result union and are returned
through `Ok`. `wip::HostError` is reserved for runtime/backend failures. Invalid
arguments are rejected before invocation; malformed encoded results are
rejected as internal host failures and never returned as application data.
through `Ok`. `wip::HostError` is reserved for runtime/backend failures. A
structurally malformed call is `InvalidRequest`; only argument values checked
after the current Interface Descriptor is fixed are `InvalidArguments`. A Host
must never return a wire `InvalidResult`: Clients keep invalid Object,
Descriptor, operation-result, and error responses as local `InvalidResponse`
failures, while unsupported descriptor formats remain local
`UnsupportedDescriptorFormat` failures.
Providers remain responsible for backend atomicity. Enter a transaction, lock,
stable-handle scope, or conditional-update primitive before constructing and
dispatching the request-scoped `PublishedObject`, and retain it until dispatch
returns. The runtime never validates one object and then resolves a second
snapshot, but it cannot make an arbitrary external backend atomic by itself.
For operation calls, `Internal` and `ResourceLimitExceeded` guarantee that the
operation did not run or that its effects were rolled back.
`OperationOutcomeUnknown` is the only protocol code that makes no such
guarantee, so Clients must not automatically retry it. `wip::HostError`
therefore requires both a `HostErrorKind` and an `EffectGuarantee`; implementation
panic, result encoding, and result validation default to an unknown outcome.
Host-private diagnostics are bounded locally but never copied into protocol
messages.
`ExecutionContext` carries a runtime-neutral cancellation token, monotonic
deadline, and optional Host-defined resource budget through resolution and
execution. Cancellation and deadlines are cooperative: the runtime checks them
immediately before typed invocation, while providers enforce them during backend
work. A pre-invocation limit failure is `ResourceLimitExceeded`; after invocation
it is safe to use that code only when non-commit or rollback is confirmed.
Providers remain responsible for backend atomicity. `with_object` returns a typed
`ProviderResult`, and `execute_operation` receives an `OperationAttempt` that
separates `NotStarted` from `Started`. A transactional provider holds its
transaction across the callback, commits successful attempts, and may call
`OperationAttempt::confirm_rollback` only after every operation effect has been
rolled back. Without that proof, post-invocation failures remain
`OperationOutcomeUnknown`. Mutable operations must still make validator
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
@@ -184,10 +265,14 @@ nix develop
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace --all-targets
cargo test --workspace --doc
cargo clippy --workspace --all-targets -- -D warnings
RUSTDOCFLAGS='-D warnings' cargo doc --workspace --no-deps
cargo run --package wip-public-api-example
git diff --check
```
`cargo test --workspace --all-targets` includes the public example integration
test, runtime failure tests, and `trybuild` compile-fail suites. Run
`cargo test --workspace --doc` when validating the checked rustdoc examples
separately.
`cargo test --workspace --all-targets` includes the public-only conformance
consumer, runtime failure tests, and `trybuild` compile-fail suites. The separate
doctest, rustdoc, executable, and whitespace checks are all required acceptance
steps.
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
+774 -206
View File
File diff suppressed because it is too large Load Diff
crates/wip-host/tests/host.rs
+891 -330
View File
File diff suppressed because it is too large Load Diff
crates/wip-host/tests/ui/unimplemented_interface.rs
+2 -3
View File
@@ -1,6 +1,5 @@
use wip_host::{InterfaceRegistry, PublishedObject, WipObject};
use wip_interface::{OperationResult, interface};
use wip_protocol::ObjectId;
#[interface]
pub trait Search {
@@ -10,8 +9,8 @@ pub trait Search {
struct Object;
impl WipObject for Object {
fn id(&self) -> ObjectId {
ObjectId("object".into())
fn name(&self) -> &str {
"object"
}
}
crates/wip-host/tests/ui/unimplemented_interface.stderr
+11 -11
View File
@@ -1,27 +1,27 @@
error[E0277]: the trait bound `Object: Search` is not satisfied
--> tests/ui/unimplemented_interface.rs:21:58
--> tests/ui/unimplemented_interface.rs:20:58
|
21 | let _published = PublishedObject::new(Object).expose(&search).unwrap();
20 | let _published = PublishedObject::new(Object).expose(&search).unwrap();
| ------ ^^^^^^^ unsatisfied trait bound
| |
| required by a bound introduced by this call
|
help: the trait `Search` is not implemented for `Object`
--> tests/ui/unimplemented_interface.rs:10:1
--> tests/ui/unimplemented_interface.rs:9:1
|
10 | struct Object;
9 | struct Object;
| ^^^^^^^^^^^^^
help: this trait has no implementations, consider adding one
--> tests/ui/unimplemented_interface.rs:6:1
|
6 | pub trait Search {
| ^^^^^^^^^^^^^^^^
note: required for `SearchDefinition` to implement `InterfaceImplementation<Object>`
--> tests/ui/unimplemented_interface.rs:5:1
|
5 | #[interface]
5 | pub trait Search {
| ^^^^^^^^^^^^^^^^
note: required for `SearchDefinition` to implement `InterfaceImplementation<Object>`
--> tests/ui/unimplemented_interface.rs:4:1
|
4 | #[interface]
| ^^^^^^^^^^^^
6 | pub trait Search {
5 | pub trait Search {
| ^^^^^^
note: required by a bound in `PublishedObject::<T>::expose`
--> src/lib.rs
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());
}
crates/wip-interface-macros/src/lib.rs
+180 -121
View File
@@ -168,9 +168,11 @@ fn expand_interface(attribute: TokenStream2, item: ItemTrait) -> syn::Result<Tok
#(#declaration_collectors)*
::wip_interface::wip_protocol::InterfaceDescriptor {
name: ::std::string::String::from(stringify!(#trait_ident)),
format: ::std::string::String::from(
::wip_interface::wip_protocol::INTERFACE_FORMAT_V1,
),
documentation: #trait_doc,
declarations,
types: declarations,
operations: ::std::vec![#(#operation_declarations),*],
}
}
@@ -180,9 +182,12 @@ fn expand_interface(attribute: TokenStream2, item: ItemTrait) -> syn::Result<Tok
fn dispatch(
implementation: &T,
operation: &str,
arguments: ::std::vec::Vec<::wip_interface::wip_protocol::NamedValue>,
arguments: ::std::collections::BTreeMap<
::std::string::String,
::wip_interface::wip_protocol::Value,
>,
) -> ::std::result::Result<
::std::option::Option<::wip_interface::wip_protocol::Value>,
::wip_interface::wip_protocol::Value,
::wip_interface::DispatchError,
> {
let descriptor = Self::descriptor();
@@ -207,9 +212,12 @@ fn expand_interface(attribute: TokenStream2, item: ItemTrait) -> syn::Result<Tok
pub fn dispatch<T: #trait_ident>(
implementation: &T,
operation: &str,
arguments: ::std::vec::Vec<::wip_interface::wip_protocol::NamedValue>,
arguments: ::std::collections::BTreeMap<
::std::string::String,
::wip_interface::wip_protocol::Value,
>,
) -> ::std::result::Result<
::std::option::Option<::wip_interface::wip_protocol::Value>,
::wip_interface::wip_protocol::Value,
::wip_interface::DispatchError,
> {
<Self as ::wip_interface::InterfaceImplementation<T>>::dispatch(
@@ -523,12 +531,11 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
let encode_result = if operation.unit_result {
quote! {
let () = result;
::std::result::Result::Ok(::std::option::Option::None)
::std::result::Result::Ok(::wip_interface::wip_protocol::Value::Unit)
}
} else {
quote! {
<#result_ty as ::wip_interface::WipType>::encode(result)
.map(::std::option::Option::Some)
}
};
@@ -541,9 +548,12 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
impl #arguments_ident {
/// Decodes named logical values into typed operation arguments.
pub fn decode(
arguments: ::std::vec::Vec<::wip_interface::wip_protocol::NamedValue>,
arguments: ::std::collections::BTreeMap<
::std::string::String,
::wip_interface::wip_protocol::Value,
>,
) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
let mut decoder = ::wip_interface::__private::RecordDecoder::new(arguments)?;
let mut decoder = ::wip_interface::__private::RecordDecoder::new(arguments);
let decoded = Self {
#(#decoders,)*
};
@@ -555,7 +565,7 @@ fn argument_item(operation: &Operation) -> TokenStream2 {
pub fn encode_result(
result: #result_ty,
) -> ::std::result::Result<
::std::option::Option<::wip_interface::wip_protocol::Value>,
::wip_interface::wip_protocol::Value,
::wip_interface::CodecError,
> {
#encode_result
@@ -575,22 +585,18 @@ fn operation_declaration(operation: &Operation) -> TokenStream2 {
quote! {
::wip_interface::wip_protocol::ParameterDeclaration {
name: ::std::string::String::from(#parameter_name),
required: !#optional,
documentation: #parameter_doc,
ty: <#ty as ::wip_interface::WipType>::type_expr(),
optional: #optional,
r#type: <#ty as ::wip_interface::WipType>::type_expr(),
}
}
});
let returns = if operation.unit_result {
quote!(::std::option::Option::None)
} else {
let result_ty = &operation.result_ty;
let return_doc = documentation_tokens(operation.return_documentation.as_ref());
quote! {
::std::option::Option::Some(::wip_interface::wip_protocol::ReturnDeclaration {
documentation: #return_doc,
ty: <#result_ty as ::wip_interface::WipType>::type_expr(),
})
let result_ty = &operation.result_ty;
let return_doc = documentation_tokens(operation.return_documentation.as_ref());
let returns = quote! {
::wip_interface::wip_protocol::ReturnDeclaration {
documentation: #return_doc,
r#type: <#result_ty as ::wip_interface::WipType>::type_expr(),
}
};
@@ -641,14 +647,17 @@ fn dispatch_arm(operation: &Operation) -> TokenStream2 {
.map_err(::wip_interface::DispatchError::InvalidArguments)?;
let decoded = #arguments_ident::decode(arguments)
.map_err(::wip_interface::DispatchError::Decode)?;
let result = implementation.#method_ident(#(#arguments),*)
.map_err(::wip_interface::DispatchError::Host)?;
let encoded = #arguments_ident::encode_result(result)
.map_err(::wip_interface::DispatchError::Encode)?;
descriptor
.validate_return(#operation_name, encoded.as_ref())
.map_err(::wip_interface::DispatchError::InvalidResult)?;
::std::result::Result::Ok(encoded)
::std::panic::catch_unwind(::std::panic::AssertUnwindSafe(|| {
let result = implementation.#method_ident(#(#arguments),*)
.map_err(::wip_interface::DispatchError::Host)?;
let encoded = #arguments_ident::encode_result(result)
.map_err(::wip_interface::DispatchError::Encode)?;
descriptor
.validate_result(#operation_name, &encoded)
.map_err(::wip_interface::DispatchError::InvalidResult)?;
::std::result::Result::Ok(encoded)
}))
.map_err(|_| ::wip_interface::DispatchError::Panic)?
}
}
}
@@ -747,9 +756,9 @@ fn derive_record(
quote! {
::wip_interface::wip_protocol::FieldDeclaration {
name: ::std::string::String::from(#name),
required: !#optional,
documentation: #documentation,
ty: <#ty as ::wip_interface::WipType>::type_expr(),
optional: #optional,
r#type: <#ty as ::wip_interface::WipType>::type_expr(),
}
}
});
@@ -765,18 +774,18 @@ fn derive_record(
if field.optional {
quote! {
if let ::std::option::Option::Some(value) = #field_ident {
fields.push(::wip_interface::wip_protocol::NamedValue {
name: ::std::string::String::from(#field_name),
value: <#ty as ::wip_interface::WipType>::encode(value)?,
});
fields.insert(
::std::string::String::from(#field_name),
<#ty as ::wip_interface::WipType>::encode(value)?,
);
}
}
} else {
quote! {
fields.push(::wip_interface::wip_protocol::NamedValue {
name: ::std::string::String::from(#field_name),
value: <#ty as ::wip_interface::WipType>::encode(#field_ident)?,
});
fields.insert(
::std::string::String::from(#field_name),
<#ty as ::wip_interface::WipType>::encode(#field_ident)?,
);
}
}
});
@@ -794,9 +803,9 @@ fn derive_record(
Ok(quote! {
impl ::wip_interface::WipType for #ident {
fn type_expr() -> ::wip_interface::wip_protocol::TypeExpr {
::wip_interface::wip_protocol::TypeExpr::Named(
::std::string::String::from(#type_name),
)
::wip_interface::wip_protocol::TypeExpr::Named {
name: ::std::string::String::from(#type_name),
}
}
fn collect_declarations(
@@ -804,13 +813,13 @@ fn derive_record(
::wip_interface::wip_protocol::TypeDeclaration,
>,
) {
let declaration = ::wip_interface::wip_protocol::TypeDeclaration::Record(
::wip_interface::wip_protocol::RecordDeclaration {
name: ::std::string::String::from(#type_name),
documentation: #declaration_doc,
let declaration = ::wip_interface::wip_protocol::TypeDeclaration {
name: ::std::string::String::from(#type_name),
documentation: #declaration_doc,
definition: ::wip_interface::wip_protocol::TypeExpr::Record {
fields: ::std::vec![#(#field_declarations),*],
},
);
};
if ::wip_interface::__private::register_declaration(declarations, declaration) {
#(#dependency_collectors)*
}
@@ -823,7 +832,7 @@ fn derive_record(
::wip_interface::CodecError,
> {
let Self { #(#destructured_fields),* } = self;
let mut fields = ::std::vec::Vec::new();
let mut fields = ::std::collections::BTreeMap::new();
#(#encoders)*
::std::result::Result::Ok(
::wip_interface::wip_protocol::Value::Record(fields),
@@ -835,7 +844,7 @@ fn derive_record(
) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
match value {
::wip_interface::wip_protocol::Value::Record(fields) => {
let mut decoder = ::wip_interface::__private::RecordDecoder::new(fields)?;
let mut decoder = ::wip_interface::__private::RecordDecoder::new(fields);
let decoded = Self {
#(#decoders,)*
};
@@ -870,14 +879,14 @@ fn derive_enum(
.variants
.iter()
.all(|variant| matches!(variant.fields, Fields::Unit));
let all_payload = !data.variants.is_empty()
&& data.variants.iter().all(|variant| {
matches!(&variant.fields, Fields::Unnamed(fields) if fields.unnamed.len() == 1)
});
let valid_union = data.variants.iter().all(|variant| {
matches!(variant.fields, Fields::Unit)
|| matches!(&variant.fields, Fields::Unnamed(fields) if fields.unnamed.len() == 1)
});
if all_unit {
derive_unit_enum(ident, type_name, type_documentation, data)
} else if all_payload {
} else if valid_union {
derive_union_enum(ident, type_name, type_documentation, data)
} else {
let span = data
@@ -890,7 +899,7 @@ fn derive_enum(
.map_or_else(|| data.enum_token.span, Spanned::span);
Err(Error::new(
span,
"a `WipType` enum must contain either only unit variants or only single-field tuple variants; mixed and named-field variants are unsupported",
"a `WipType` enum must contain unit variants and/or single-field tuple variants; named-field and multi-field variants are unsupported",
))
}
}
@@ -906,7 +915,7 @@ fn derive_unit_enum(
let name = source_name(&variant.ident);
let documentation = documentation_tokens(documentation(&variant.attrs).as_ref());
quote! {
::wip_interface::wip_protocol::EnumVariantDeclaration {
::wip_interface::wip_protocol::EnumCase {
name: ::std::string::String::from(#name),
documentation: #documentation,
}
@@ -926,9 +935,9 @@ fn derive_unit_enum(
Ok(quote! {
impl ::wip_interface::WipType for #ident {
fn type_expr() -> ::wip_interface::wip_protocol::TypeExpr {
::wip_interface::wip_protocol::TypeExpr::Named(
::std::string::String::from(#type_name),
)
::wip_interface::wip_protocol::TypeExpr::Named {
name: ::std::string::String::from(#type_name),
}
}
fn collect_declarations(
@@ -936,13 +945,13 @@ fn derive_unit_enum(
::wip_interface::wip_protocol::TypeDeclaration,
>,
) {
let declaration = ::wip_interface::wip_protocol::TypeDeclaration::Enum(
::wip_interface::wip_protocol::EnumDeclaration {
name: ::std::string::String::from(#type_name),
documentation: #declaration_doc,
variants: ::std::vec![#(#declarations),*],
let declaration = ::wip_interface::wip_protocol::TypeDeclaration {
name: ::std::string::String::from(#type_name),
documentation: #declaration_doc,
definition: ::wip_interface::wip_protocol::TypeExpr::Enum {
cases: ::std::vec![#(#declarations),*],
},
);
};
let _ = ::wip_interface::__private::register_declaration(
declarations,
declaration,
@@ -959,7 +968,7 @@ fn derive_unit_enum(
#(#encoders,)*
};
::std::result::Result::Ok(
::wip_interface::wip_protocol::Value::Enum(
::wip_interface::wip_protocol::Value::String(
::std::string::String::from(variant),
),
)
@@ -969,7 +978,7 @@ fn derive_unit_enum(
value: ::wip_interface::wip_protocol::Value,
) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
match value {
::wip_interface::wip_protocol::Value::Enum(variant) => {
::wip_interface::wip_protocol::Value::String(variant) => {
match variant.as_str() {
#(#decoders,)*
_ => ::std::result::Result::Err(
@@ -998,35 +1007,36 @@ fn derive_union_enum(
struct Variant<'a> {
ident: &'a Ident,
name: String,
ty: &'a Type,
payload: Option<&'a Type>,
documentation: Option<Documentation>,
}
let mut variants = Vec::new();
for variant in &data.variants {
let Fields::Unnamed(fields) = &variant.fields else {
return Err(Error::new_spanned(
variant,
"a `WipType` union variant must contain exactly one unnamed field",
));
let payload = match &variant.fields {
Fields::Unit => None,
Fields::Unnamed(fields) if fields.unnamed.len() == 1 => {
let field = fields.unnamed.first().expect("length checked");
if direct_option(&field.ty)?.is_some() || contains_option(&field.ty) {
return Err(Error::new_spanned(
&field.ty,
"`Option<T>` is only supported directly on DTO fields and operation parameters",
));
}
validate_value_type(&field.ty, "union case payload")?;
Some(&field.ty)
}
_ => {
return Err(Error::new_spanned(
variant,
"a `WipType` union case must be unit-like or contain exactly one unnamed payload",
));
}
};
let Some(field) = fields.unnamed.first() else {
return Err(Error::new_spanned(
fields,
"a `WipType` union variant must contain exactly one unnamed field",
));
};
if direct_option(&field.ty)?.is_some() || contains_option(&field.ty) {
return Err(Error::new_spanned(
&field.ty,
"`Option<T>` is only supported directly on DTO fields and operation parameters",
));
}
validate_value_type(&field.ty, "union variant payload")?;
variants.push(Variant {
ident: &variant.ident,
name: source_name(&variant.ident),
ty: &field.ty,
payload,
documentation: documentation(&variant.attrs),
});
}
@@ -1035,50 +1045,95 @@ fn derive_union_enum(
let declarations = variants.iter().map(|variant| {
let name = &variant.name;
let documentation = documentation_tokens(variant.documentation.as_ref());
let ty = variant.ty;
let payload = match variant.payload {
Some(ty) => quote! {
::std::option::Option::Some(
<#ty as ::wip_interface::WipType>::type_expr(),
)
},
None => quote!(::std::option::Option::None),
};
quote! {
::wip_interface::wip_protocol::UnionVariantDeclaration {
::wip_interface::wip_protocol::UnionCase {
name: ::std::string::String::from(#name),
documentation: #documentation,
ty: <#ty as ::wip_interface::WipType>::type_expr(),
payload: #payload,
}
}
});
let dependency_collectors = variants.iter().map(|variant| {
let ty = variant.ty;
quote!(<#ty as ::wip_interface::WipType>::collect_declarations(declarations);)
let dependency_collectors = variants.iter().filter_map(|variant| {
variant.payload.map(
|ty| quote!(<#ty as ::wip_interface::WipType>::collect_declarations(declarations);),
)
});
let encoders = variants.iter().map(|variant| {
let variant_ident = variant.ident;
let name = &variant.name;
let ty = variant.ty;
quote! {
Self::#variant_ident(value) => {
::wip_interface::wip_protocol::Value::Union {
variant: ::std::string::String::from(#name),
value: ::std::boxed::Box::new(
match variant.payload {
Some(ty) => quote! {
Self::#variant_ident(value) => {
let mut fields = ::std::collections::BTreeMap::new();
fields.insert(
::std::string::String::from(
::wip_interface::wip_protocol::UNION_CASE_FIELD,
),
::wip_interface::wip_protocol::Value::String(
::std::string::String::from(#name),
),
);
fields.insert(
::std::string::String::from(
::wip_interface::wip_protocol::UNION_VALUE_FIELD,
),
<#ty as ::wip_interface::WipType>::encode(value)?,
),
);
::wip_interface::wip_protocol::Value::Record(fields)
}
}
},
None => quote! {
Self::#variant_ident => {
let mut fields = ::std::collections::BTreeMap::new();
fields.insert(
::std::string::String::from(
::wip_interface::wip_protocol::UNION_CASE_FIELD,
),
::wip_interface::wip_protocol::Value::String(
::std::string::String::from(#name),
),
);
::wip_interface::wip_protocol::Value::Record(fields)
}
},
}
});
let decoders = variants.iter().map(|variant| {
let variant_ident = variant.ident;
let name = &variant.name;
let ty = variant.ty;
quote! {
#name => <#ty as ::wip_interface::WipType>::decode(*value)
.map(Self::#variant_ident)
match variant.payload {
Some(ty) => quote! {
#name => {
let value = decoder.required::<#ty>(
::wip_interface::wip_protocol::UNION_VALUE_FIELD,
)?;
decoder.finish()?;
::std::result::Result::Ok(Self::#variant_ident(value))
}
},
None => quote! {
#name => {
decoder.finish()?;
::std::result::Result::Ok(Self::#variant_ident)
}
},
}
});
Ok(quote! {
impl ::wip_interface::WipType for #ident {
fn type_expr() -> ::wip_interface::wip_protocol::TypeExpr {
::wip_interface::wip_protocol::TypeExpr::Named(
::std::string::String::from(#type_name),
)
::wip_interface::wip_protocol::TypeExpr::Named {
name: ::std::string::String::from(#type_name),
}
}
fn collect_declarations(
@@ -1086,13 +1141,13 @@ fn derive_union_enum(
::wip_interface::wip_protocol::TypeDeclaration,
>,
) {
let declaration = ::wip_interface::wip_protocol::TypeDeclaration::Union(
::wip_interface::wip_protocol::UnionDeclaration {
name: ::std::string::String::from(#type_name),
documentation: #declaration_doc,
variants: ::std::vec![#(#declarations),*],
let declaration = ::wip_interface::wip_protocol::TypeDeclaration {
name: ::std::string::String::from(#type_name),
documentation: #declaration_doc,
definition: ::wip_interface::wip_protocol::TypeExpr::Union {
cases: ::std::vec![#(#declarations),*],
},
);
};
if ::wip_interface::__private::register_declaration(declarations, declaration) {
#(#dependency_collectors)*
}
@@ -1114,26 +1169,30 @@ fn derive_union_enum(
value: ::wip_interface::wip_protocol::Value,
) -> ::std::result::Result<Self, ::wip_interface::CodecError> {
match value {
::wip_interface::wip_protocol::Value::Union { variant, value } => {
match variant.as_str() {
::wip_interface::wip_protocol::Value::Record(fields) => {
let mut decoder =
::wip_interface::__private::RecordDecoder::new(fields);
let case = decoder.required::<::std::string::String>(
::wip_interface::wip_protocol::UNION_CASE_FIELD,
)?;
match case.as_str() {
#(#decoders,)*
_ => ::std::result::Result::Err(
::wip_interface::__private::decode_unknown_variant(
#type_name,
variant,
case,
),
),
}
}
actual => ::std::result::Result::Err(
::wip_interface::__private::decode_type_mismatch("union", actual),
::wip_interface::__private::decode_type_mismatch("union record", actual),
),
}
}
}
})
}
fn optional_type(ty: &Type, context: &str) -> syn::Result<(bool, Type)> {
if let Some(inner) = direct_option(ty)? {
if contains_option(&inner) {
crates/wip-interface/src/lib.rs
+343 -107
View File
@@ -30,52 +30,65 @@
//!
//! | Rust type | Protocol type/value |
//! | --- | --- |
//! | `()` as an operation result | no return declaration / no value |
//! | `()` | `Unit` |
//! | `bool` | `Boolean` |
//! | signed and unsigned integer primitives | JavaScript-lossless `Integer` |
//! | `f32`, `f64` | finite `Number` |
//! | `String` | `String` |
//! | [`Bytes`] | `Bytes` |
//! | [`wip_protocol::JsonValue`] | `Json` |
//! | [`Entry<K, V>`] | `Entry<K, V>` |
//! | [`JsonValue`] | schema-neutral `Json` value tree |
//! | [`Entry`] | canonical absolute Worldspace path (`Entry`) |
//! | `Vec<T>` | `List<T>` |
//! | a named-field struct deriving [`WipType`] | named record |
//! | an all-unit enum deriving [`WipType`] | named enum |
//! | an all-newtype enum deriving [`WipType`] | named tagged union |
//! | an enum mixing unit and single-payload cases deriving [`WipType`] | named union |
//!
//! `Option<T>` is supported only directly as a record field or operation
//! parameter. It means omission, not a null value. A domain failure belongs in
//! an application return enum/union and is returned as `Ok(value)`.
//! [`HostError`] is reserved for host/runtime failure, so the required
//! [`OperationResult`] convention keeps those two failure classes distinct.
//! [`HostError`] is reserved for host/runtime failure and requires an explicit
//! [`HostErrorKind`] plus [`EffectGuarantee`]. The required [`OperationResult`]
//! convention therefore keeps domain failures separate from runtime failures and
//! makes outcome uncertainty visible to Host dispatch.
//!
//! # Migration to canonical values
//!
//! Earlier releases exposed `Entry<K, V>` and semantic `Value::Json`,
//! `Value::Entry`, `Value::Enum`, and `Value::Union` variants. Those forms are
//! intentionally gone: [`Entry`] is now one validated absolute Worldspace path,
//! while JSON, enum, and union meaning comes only from the descriptor. Codecs
//! exchange only raw [`Value`] strings, records, lists, and primitives. Unit
//! operation results now cross the boundary as [`Value::Unit`] rather than an
//! absent value.
//!
//! # Supported interface syntax
//!
//! An interface is a public, non-generic trait whose operations use exactly
//! `&self`, simple named owned parameters, and an explicit
//! `OperationResult<T>`. `WipType` derives support named-field structs,
//! all-unit enums, and all-single-payload enums.
//! all-unit enums as protocol enums, and enums made from any mix of unit and
//! single-payload cases as protocol unions.
//!
//! The macros reject trait inheritance and associated items; const, async,
//! unsafe, extern, variadic, generic, default-bodied, or non-`&self` methods;
//! borrowed values and custom lifetimes; tuple, unit, or generic structs;
//! mixed or named-field enum variants; explicit discriminants; Rust unions;
//! unsupported named-field or multi-field enum variants; explicit discriminants; Rust unions;
//! and `Option` anywhere except a direct DTO field or operation parameter.
//! Unsupported inputs produce source-located compile errors rather than
//! generating a partial interface.
#![deny(missing_docs)]
use std::collections::BTreeMap;
use std::error::Error;
use std::fmt::{self, Display, Formatter};
pub use wip_interface_macros::{WipType, interface};
pub use wip_protocol;
pub use wip_protocol::{
Documentation, EnumDeclaration, EnumVariantDeclaration, FieldDeclaration, InterfaceDescriptor,
JsonMember, JsonValue, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, NamedValue, OperationDeclaration,
ParameterDeclaration, RecordDeclaration, ReturnDeclaration, TypeDeclaration, TypeExpr,
UnionDeclaration, UnionVariantDeclaration, ValidationError, Value,
Documentation, EnumCase, FieldDeclaration, InterfaceDescriptor, MAX_SAFE_INTEGER,
MIN_SAFE_INTEGER, OperationDeclaration, ParameterDeclaration, ReturnDeclaration,
TypeDeclaration, TypeExpr, UnionCase, ValidationError, Value,
};
/// Converts one Rust application type to and from its protocol representation.
@@ -118,8 +131,8 @@ pub trait InterfaceImplementation<T>: InterfaceDefinition {
fn dispatch(
implementation: &T,
operation: &str,
arguments: Vec<NamedValue>,
) -> Result<Option<Value>, DispatchError>;
arguments: BTreeMap<String, Value>,
) -> Result<Value, DispatchError>;
}
/// Result convention required for generated interface operations.
@@ -128,29 +141,107 @@ pub trait InterfaceImplementation<T>: InterfaceDefinition {
/// `Err(HostError)` means the host or runtime could not perform the operation.
pub type OperationResult<T> = Result<T, HostError>;
/// A host/runtime failure, kept separate from the operation's application
/// Whether an operation failure proves that no effects were committed.
///
/// This guarantee is consumed by Host dispatch when choosing a protocol failure:
/// only [`NotCommitted`](Self::NotCommitted) failures may become `Internal` or
/// `ResourceLimitExceeded`; [`Unknown`](Self::Unknown) failures must become
/// `OperationOutcomeUnknown`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EffectGuarantee {
/// The operation was not invoked, or every effect was rolled back.
NotCommitted,
/// The operation may have committed effects.
Unknown,
}
/// Host/runtime failure category used when effects are known not to be committed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostErrorKind {
/// The Host or backend encountered an internal failure.
Internal,
/// A cancellation, deadline, or bounded resource limit was exceeded.
ResourceLimitExceeded,
}
/// A typed host/runtime failure, kept separate from the operation's application
/// return type.
///
/// The effect guarantee is mandatory. Host runtimes must ignore the diagnostic
/// when producing a wire response; it is bounded here for local observability but
/// can still contain backend-private information.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HostError {
kind: HostErrorKind,
effect_guarantee: EffectGuarantee,
message: String,
}
impl HostError {
/// Creates a host failure with a human-readable diagnostic.
/// Creates an internal Host failure with an explicit effect guarantee.
#[must_use]
pub fn new(message: impl Into<String>) -> Self {
pub fn internal(message: impl Into<String>, effect_guarantee: EffectGuarantee) -> Self {
Self::new(HostErrorKind::Internal, effect_guarantee, message)
}
/// Creates a resource-limit Host failure with an explicit effect guarantee.
#[must_use]
pub fn resource_limit(message: impl Into<String>, effect_guarantee: EffectGuarantee) -> Self {
Self::new(
HostErrorKind::ResourceLimitExceeded,
effect_guarantee,
message,
)
}
fn new(
kind: HostErrorKind,
effect_guarantee: EffectGuarantee,
message: impl Into<String>,
) -> Self {
Self {
message: message.into(),
kind,
effect_guarantee,
message: bounded_diagnostic(message.into()),
}
}
/// Returns the diagnostic message.
/// Returns the typed Host failure category.
#[must_use]
pub fn kind(&self) -> HostErrorKind {
self.kind
}
/// Returns the operation-effect guarantee attached by the implementation.
#[must_use]
pub fn effect_guarantee(&self) -> EffectGuarantee {
self.effect_guarantee
}
/// Returns the bounded local diagnostic message.
///
/// Host runtimes must not place this value in protocol responses because it
/// can contain backend paths, credentials, or other private details.
#[must_use]
pub fn message(&self) -> &str {
&self.message
}
}
const MAX_DIAGNOSTIC_BYTES: usize = 512;
fn bounded_diagnostic(mut message: String) -> String {
if message.len() <= MAX_DIAGNOSTIC_BYTES {
return message;
}
let mut end = MAX_DIAGNOSTIC_BYTES;
while !message.is_char_boundary(end) {
end -= 1;
}
message.truncate(end);
message
}
impl Display for HostError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.message)
@@ -230,12 +321,59 @@ pub enum DispatchError {
Decode(CodecError),
/// The implementation reported a host/runtime failure.
Host(HostError),
/// The implementation panicked after invocation began.
///
/// Panic payloads are deliberately discarded because they can contain
/// backend-private diagnostics.
Panic,
/// The Rust result could not be encoded.
Encode(CodecError),
/// The encoded result did not match the generated declaration.
InvalidResult(wip_protocol::ValidationError),
}
/// Whether generated dispatch failed before or after typed implementation
/// invocation began.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DispatchPhase {
/// Typed implementation code was not invoked.
BeforeInvocation,
/// Typed implementation invocation began, so effects require an explicit
/// non-commit or rollback guarantee.
AfterInvocation,
}
impl DispatchError {
/// Returns the execution phase in which this dispatch failure occurred.
#[must_use]
pub fn phase(&self) -> DispatchPhase {
match self {
Self::UnknownOperation(_) | Self::InvalidArguments(_) | Self::Decode(_) => {
DispatchPhase::BeforeInvocation
}
Self::Host(_) | Self::Panic | Self::Encode(_) | Self::InvalidResult(_) => {
DispatchPhase::AfterInvocation
}
}
}
/// Returns a post-invocation effect guarantee when the implementation
/// supplied one.
///
/// Panic, encode, and result-validation failures default to `Unknown` until
/// a provider confirms rollback. Pre-invocation failures return `None`.
#[must_use]
pub fn effect_guarantee(&self) -> Option<EffectGuarantee> {
match self {
Self::UnknownOperation(_) | Self::InvalidArguments(_) | Self::Decode(_) => None,
Self::Host(error) => Some(error.effect_guarantee()),
Self::Panic | Self::Encode(_) | Self::InvalidResult(_) => {
Some(EffectGuarantee::Unknown)
}
}
}
}
impl Display for DispatchError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
@@ -245,6 +383,7 @@ impl Display for DispatchError {
Self::InvalidArguments(error) => write!(formatter, "invalid arguments: {error}"),
Self::Decode(error) => write!(formatter, "argument decoding failed: {error}"),
Self::Host(error) => write!(formatter, "host operation failed: {error}"),
Self::Panic => formatter.write_str("operation implementation panicked"),
Self::Encode(error) => write!(formatter, "result encoding failed: {error}"),
Self::InvalidResult(error) => write!(formatter, "invalid operation result: {error}"),
}
@@ -254,7 +393,7 @@ impl Display for DispatchError {
impl Error for DispatchError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::UnknownOperation(_) => None,
Self::UnknownOperation(_) | Self::Panic => None,
Self::InvalidArguments(error) | Self::InvalidResult(error) => Some(error),
Self::Decode(error) | Self::Encode(error) => Some(error),
Self::Host(error) => Some(error),
@@ -281,13 +420,101 @@ impl From<Bytes> for Vec<u8> {
}
}
/// A typed protocol key/value entry.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Entry<K, V> {
/// Entry key.
pub key: K,
/// Entry value.
pub value: V,
/// A canonical absolute path to an entry in the current Worldspace.
///
/// This replaces the pre-canonical `Entry<K, V>` key/value pair. Construct an
/// entry from a path such as `/articles/1`; application data associated with
/// that entry belongs in an ordinary record alongside this value.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Entry(String);
impl Entry {
/// Validates and creates an entry path.
pub fn new(path: impl Into<String>) -> Result<Self, CodecError> {
let path = path.into();
validate_entry_path(&path)?;
Ok(Self(path))
}
/// Returns the canonical absolute Worldspace path.
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
/// Consumes the entry and returns its path.
#[must_use]
pub fn into_string(self) -> String {
self.0
}
}
impl TryFrom<String> for Entry {
type Error = CodecError;
fn try_from(path: String) -> Result<Self, Self::Error> {
Self::new(path)
}
}
impl std::str::FromStr for Entry {
type Err = CodecError;
fn from_str(path: &str) -> Result<Self, Self::Err> {
Self::new(path)
}
}
/// One member in a [`JsonValue::Object`].
#[derive(Debug, Clone, PartialEq)]
pub struct JsonMember {
/// Member name.
pub name: String,
/// Member value.
pub value: JsonValue,
}
/// JSON data represented independently of any application schema.
///
/// Its codec uses the ordinary schema-neutral [`Value`] variants. JSON null is
/// [`Value::Unit`], arrays are [`Value::List`], and objects are
/// [`Value::Record`]. Protocol bytes have no JSON representation and decoding
/// a tree containing [`Value::Bytes`] is rejected.
#[derive(Debug, Clone, PartialEq)]
pub enum JsonValue {
/// JSON null.
Null,
/// A JSON boolean.
Boolean(bool),
/// An interoperable integral JSON number.
Integer(i64),
/// A finite non-integral JSON number.
Number(f64),
/// A JSON string.
String(String),
/// A JSON array.
Array(Vec<JsonValue>),
/// A JSON object. Duplicate member names are rejected while encoding.
Object(Vec<JsonMember>),
}
impl WipType for () {
fn type_expr() -> TypeExpr {
TypeExpr::Unit
}
fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
fn encode(self) -> Result<Value, CodecError> {
Ok(Value::Unit)
}
fn decode(value: Value) -> Result<Self, CodecError> {
match value {
Value::Unit => Ok(()),
other => Err(CodecError::expected("unit", &other)),
}
}
}
impl WipType for bool {
@@ -456,52 +683,87 @@ impl WipType for JsonValue {
fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
fn encode(self) -> Result<Value, CodecError> {
validate_json(&self)?;
Ok(Value::Json(self))
encode_json(self)
}
fn decode(value: Value) -> Result<Self, CodecError> {
match value {
Value::Json(value) => {
validate_json(&value)?;
Ok(value)
decode_json(value)
}
}
fn encode_json(value: JsonValue) -> Result<Value, CodecError> {
match value {
JsonValue::Null => Ok(Value::Unit),
JsonValue::Boolean(value) => Ok(Value::Boolean(value)),
JsonValue::Integer(value) => {
ensure_safe_integer(value)?;
Ok(Value::Integer(value))
}
JsonValue::Number(value) => {
ensure_finite(value)?;
Ok(Value::Number(value))
}
JsonValue::String(value) => Ok(Value::String(value)),
JsonValue::Array(values) => values
.into_iter()
.enumerate()
.map(|(index, value)| encode_json(value).map_err(|error| error.at(index.to_string())))
.collect::<Result<Vec<_>, _>>()
.map(Value::List),
JsonValue::Object(members) => {
let mut fields = BTreeMap::new();
for member in members {
let name = member.name;
let value = encode_json(member.value).map_err(|error| error.at(name.clone()))?;
if fields.insert(name.clone(), value).is_some() {
return Err(CodecError::new(format!("duplicate JSON member `{name}`")).at(name));
}
}
other => Err(CodecError::expected("json", &other)),
Ok(Value::Record(fields))
}
}
}
fn validate_json(value: &JsonValue) -> Result<(), CodecError> {
fn decode_json(value: Value) -> Result<JsonValue, CodecError> {
match value {
JsonValue::Integer(value) => ensure_safe_integer(*value),
JsonValue::Number(value) => ensure_finite(*value),
JsonValue::Array(values) => {
for (index, value) in values.iter().enumerate() {
validate_json(value).map_err(|error| error.at(index.to_string()))?;
}
Ok(())
Value::Unit => Ok(JsonValue::Null),
Value::Boolean(value) => Ok(JsonValue::Boolean(value)),
Value::Integer(value) => {
ensure_safe_integer(value)?;
Ok(JsonValue::Integer(value))
}
JsonValue::Object(members) => {
let mut names = std::collections::HashSet::new();
for member in members {
if !names.insert(member.name.as_str()) {
return Err(CodecError::new(format!(
"duplicate JSON member `{}`",
member.name
))
.at(member.name.clone()));
}
validate_json(&member.value).map_err(|error| error.at(member.name.clone()))?;
}
Ok(())
Value::Number(value) => {
ensure_finite(value)?;
Ok(JsonValue::Number(value))
}
JsonValue::Null | JsonValue::Boolean(_) | JsonValue::String(_) => Ok(()),
Value::String(value) => Ok(JsonValue::String(value)),
Value::Bytes(_) => Err(CodecError::new("bytes are not valid inside JSON")),
Value::List(values) => values
.into_iter()
.enumerate()
.map(|(index, value)| decode_json(value).map_err(|error| error.at(index.to_string())))
.collect::<Result<Vec<_>, _>>()
.map(JsonValue::Array),
Value::Record(fields) => fields
.into_iter()
.map(|(name, value)| {
decode_json(value)
.map(|value| JsonMember {
name: name.clone(),
value,
})
.map_err(|error| error.at(name))
})
.collect::<Result<Vec<_>, _>>()
.map(JsonValue::Object),
}
}
impl<T: WipType> WipType for Vec<T> {
fn type_expr() -> TypeExpr {
TypeExpr::List(Box::new(T::type_expr()))
TypeExpr::List {
items: Box::new(T::type_expr()),
}
}
fn collect_declarations(declarations: &mut Vec<TypeDeclaration>) {
@@ -528,37 +790,31 @@ impl<T: WipType> WipType for Vec<T> {
}
}
impl<K: WipType, V: WipType> WipType for Entry<K, V> {
impl WipType for Entry {
fn type_expr() -> TypeExpr {
TypeExpr::Entry {
key: Box::new(K::type_expr()),
value: Box::new(V::type_expr()),
}
TypeExpr::Entry
}
fn collect_declarations(declarations: &mut Vec<TypeDeclaration>) {
K::collect_declarations(declarations);
V::collect_declarations(declarations);
}
fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
fn encode(self) -> Result<Value, CodecError> {
Ok(Value::Entry {
key: Box::new(self.key.encode().map_err(|error| error.at("key"))?),
value: Box::new(self.value.encode().map_err(|error| error.at("value"))?),
})
validate_entry_path(&self.0)?;
Ok(Value::String(self.0))
}
fn decode(value: Value) -> Result<Self, CodecError> {
let Value::Entry { key, value } = value else {
return Err(CodecError::expected("entry", &value));
let Value::String(path) = value else {
return Err(CodecError::expected("entry path string", &value));
};
Ok(Self {
key: K::decode(*key).map_err(|error| error.at("key"))?,
value: V::decode(*value).map_err(|error| error.at("value"))?,
})
Self::new(path)
}
}
fn validate_entry_path(path: &str) -> Result<(), CodecError> {
wip_protocol::validate_path(path)
.map_err(|error| CodecError::new(format!("invalid canonical Worldspace path: {error}")))
}
/// Implementation details used by code emitted from the facade's macros.
///
/// These APIs are public only because macro expansions execute in the
@@ -566,12 +822,9 @@ impl<K: WipType, V: WipType> WipType for Entry<K, V> {
/// and are not intended for direct use.
#[doc(hidden)]
pub mod __private {
use std::collections::HashSet;
use std::collections::BTreeMap;
use wip_protocol::{
InterfaceDescriptor, NamedValue, ObjectId, OperationCall, OperationTarget, TypeDeclaration,
ValidationError, Value,
};
use wip_protocol::{InterfaceDescriptor, TypeDeclaration, ValidationError, Value};
use crate::{CodecError, Documentation, WipType};
@@ -606,16 +859,9 @@ pub mod __private {
pub fn validate_arguments(
descriptor: &InterfaceDescriptor,
operation: &str,
arguments: &[NamedValue],
arguments: &BTreeMap<String, Value>,
) -> Result<(), ValidationError> {
descriptor.validate_call(&OperationCall {
target: OperationTarget {
object: ObjectId("<typed-dispatch>".into()),
interface: descriptor.name.clone(),
operation: operation.into(),
},
arguments: arguments.to_vec(),
})
descriptor.validate_arguments(operation, arguments)
}
/// Builds a codec error for a generated structural mismatch.
@@ -633,21 +879,13 @@ pub mod __private {
/// Decoder for a protocol record or operation's named argument collection.
pub struct RecordDecoder {
fields: Vec<NamedValue>,
fields: BTreeMap<String, Value>,
}
impl RecordDecoder {
/// Starts decoding record fields or named operation arguments and
/// rejects duplicate names.
pub fn new(fields: Vec<NamedValue>) -> Result<Self, CodecError> {
let mut seen = HashSet::new();
for field in &fields {
if !seen.insert(field.name.clone()) {
return Err(CodecError::new(format!("duplicate field `{}`", field.name))
.at(field.name.clone()));
}
}
Ok(Self { fields })
/// Starts decoding record fields or named operation arguments.
pub fn new(fields: BTreeMap<String, Value>) -> Self {
Self { fields }
}
/// Decodes a required field.
@@ -668,17 +906,15 @@ pub mod __private {
/// Rejects any fields that were not consumed by generated code.
pub fn finish(self) -> Result<(), CodecError> {
if let Some(field) = self.fields.first() {
Err(CodecError::new(format!("unknown field `{}`", field.name))
.at(field.name.clone()))
if let Some(name) = self.fields.keys().next() {
Err(CodecError::new(format!("unknown field `{name}`")).at(name.clone()))
} else {
Ok(())
}
}
fn take(&mut self, name: &str) -> Option<Value> {
let index = self.fields.iter().position(|field| field.name == name)?;
Some(self.fields.remove(index).value)
self.fields.remove(name)
}
}
}
crates/wip-interface/tests/codecs.rs
+112 -49
View File
@@ -1,8 +1,7 @@
use wip_interface::wip_protocol::{
EnumDeclaration, JsonMember, JsonValue, NamedValue, RecordDeclaration, TypeDeclaration,
TypeExpr, UnionDeclaration, Value,
};
use wip_interface::{Bytes, Entry, WipType};
use std::collections::BTreeMap;
use wip_interface::wip_protocol::{TypeExpr, UNION_CASE_FIELD, UNION_VALUE_FIELD, Value};
use wip_interface::{Bytes, Entry, JsonMember, JsonValue, WipType};
/// A request record.
#[derive(Debug, Clone, PartialEq, WipType)]
@@ -11,8 +10,8 @@ struct Request {
title: String,
/// Optional priority.
priority: Option<i32>,
/// Related entries.
related: Vec<Entry<String, bool>>,
/// Related Worldspace entries.
related: Vec<Entry>,
/// Opaque bytes.
body: Bytes,
/// Arbitrary metadata.
@@ -38,33 +37,53 @@ struct Receipt {
/// Application-level publication outcome.
#[derive(Debug, Clone, PartialEq, WipType)]
enum PublishOutcome {
/// Work has not completed and carries no payload.
Pending,
/// Application success.
Published(Receipt),
/// Domain rejection, not a host failure.
Rejected(String),
}
fn field<'a>(record: &'a BTreeMap<String, Value>, name: &str) -> &'a Value {
record
.get(name)
.unwrap_or_else(|| panic!("missing `{name}`"))
}
#[test]
fn supported_values_round_trip() {
fn primitive_unit_record_list_entry_and_json_values_round_trip() {
assert_eq!(().encode().unwrap(), Value::Unit);
assert_eq!(<()>::decode(Value::Unit).unwrap(), ());
assert_eq!(<()>::type_expr(), TypeExpr::Unit);
let request = Request {
title: "hello".into(),
priority: None,
related: vec![Entry {
key: "/articles/1".into(),
value: true,
}],
related: vec![Entry::new("/articles/1").unwrap()],
body: Bytes(vec![1, 2, 3]),
metadata: JsonValue::Object(vec![JsonMember {
name: "source".into(),
value: JsonValue::String("test".into()),
value: JsonValue::Array(vec![JsonValue::String("test".into()), JsonValue::Null]),
}]),
};
let encoded = request.clone().encode().unwrap();
let Value::Record(fields) = &encoded else {
panic!("record derive must encode a protocol record")
panic!("record derive must encode a raw protocol record")
};
assert!(fields.iter().all(|field| field.name != "priority"));
assert!(!fields.contains_key("priority"));
assert_eq!(
field(fields, "related"),
&Value::List(vec![Value::String("/articles/1".into())])
);
assert_eq!(
field(fields, "metadata"),
&Value::Record(BTreeMap::from([(
"source".into(),
Value::List(vec![Value::String("test".into()), Value::Unit]),
)]))
);
assert_eq!(Request::decode(encoded).unwrap(), request);
let number = 42.5_f64;
@@ -77,92 +96,136 @@ fn supported_values_round_trip() {
f32::decode(narrow_number.encode().unwrap()).unwrap(),
narrow_number
);
}
#[test]
fn enums_are_strings_and_unions_are_discriminated_records() {
for color in [Color::Red, Color::Blue] {
let encoded = color.clone().encode().unwrap();
let decoded = Color::decode(encoded).unwrap();
assert_eq!(decoded, color);
assert!(matches!(encoded, Value::String(_)));
assert_eq!(Color::decode(encoded).unwrap(), color);
}
let pending = PublishOutcome::Pending.encode().unwrap();
assert_eq!(
pending,
Value::Record(BTreeMap::from([(
UNION_CASE_FIELD.into(),
Value::String("Pending".into()),
)]))
);
let published = PublishOutcome::Published(Receipt { number: 7 })
.encode()
.unwrap();
let Value::Record(fields) = &published else {
panic!("union must encode as a record")
};
assert_eq!(
fields.get(UNION_CASE_FIELD),
Some(&Value::String("Published".into()))
);
assert!(matches!(
fields.get(UNION_VALUE_FIELD),
Some(Value::Record(_))
));
for outcome in [
PublishOutcome::Pending,
PublishOutcome::Published(Receipt { number: 7 }),
PublishOutcome::Rejected("policy".into()),
] {
let encoded = outcome.clone().encode().unwrap();
let decoded = PublishOutcome::decode(encoded).unwrap();
assert_eq!(decoded, outcome);
assert_eq!(PublishOutcome::decode(encoded).unwrap(), outcome);
}
}
#[test]
fn derived_declarations_include_docs_optionality_and_dependencies() {
fn derived_declarations_use_canonical_named_type_expressions() {
let mut declarations = Vec::new();
Request::collect_declarations(&mut declarations);
Color::collect_declarations(&mut declarations);
PublishOutcome::collect_declarations(&mut declarations);
let TypeDeclaration::Record(RecordDeclaration {
documentation,
fields,
..
}) = &declarations[0]
else {
let request = declarations
.iter()
.find(|declaration| declaration.name == "Request")
.unwrap();
assert_eq!(
request.documentation.as_ref().unwrap().summary,
"A request record."
);
let TypeExpr::Record { fields } = &request.definition else {
panic!("Request must be a record declaration")
};
assert_eq!(documentation.as_ref().unwrap().summary, "A request record.");
assert_eq!(
fields[0].documentation.as_ref().unwrap().summary,
"Required title."
);
assert!(!fields[0].optional);
assert!(fields[1].optional);
assert_eq!(fields[1].ty, TypeExpr::Integer);
assert!(fields[0].required);
assert!(!fields[1].required);
assert_eq!(fields[1].r#type, TypeExpr::Integer);
assert_eq!(
fields[2].ty,
TypeExpr::List(Box::new(TypeExpr::Entry {
key: Box::new(TypeExpr::String),
value: Box::new(TypeExpr::Boolean),
}))
fields[2].r#type,
TypeExpr::List {
items: Box::new(TypeExpr::Entry),
}
);
let color = declarations
.iter()
.find(|declaration| declaration.name() == "Color")
.find(|declaration| declaration.name == "Color")
.unwrap();
let TypeDeclaration::Enum(EnumDeclaration { variants, .. }) = color else {
let TypeExpr::Enum { cases } = &color.definition else {
panic!("Color must be an enum declaration")
};
assert_eq!(
variants[0].documentation.as_ref().unwrap().summary,
cases[0].documentation.as_ref().unwrap().summary,
"Warm red."
);
let outcome = declarations
.iter()
.find(|declaration| declaration.name() == "PublishOutcome")
.find(|declaration| declaration.name == "PublishOutcome")
.unwrap();
let TypeDeclaration::Union(UnionDeclaration { variants, .. }) = outcome else {
let TypeExpr::Union { cases } = &outcome.definition else {
panic!("PublishOutcome must be a union declaration")
};
assert_eq!(variants[0].ty, TypeExpr::Named("Receipt".into()));
assert_eq!(cases[0].payload, None);
assert_eq!(
cases[1].payload,
Some(TypeExpr::Named {
name: "Receipt".into(),
})
);
assert!(
declarations
.iter()
.any(|declaration| declaration.name() == "Receipt")
.any(|declaration| declaration.name == "Receipt")
);
}
#[test]
fn codecs_reject_invalid_boundaries() {
fn codecs_reject_invalid_boundaries_and_json_bytes() {
assert!(i64::MAX.encode().is_err());
assert!(f64::NAN.encode().is_err());
assert!(Request::decode(Value::Record(vec![])).is_err());
assert!(Request::decode(Value::Record(BTreeMap::new())).is_err());
assert!(
Request::decode(Value::Record(vec![NamedValue {
name: "unknown".into(),
value: Value::String("value".into()),
}]))
Request::decode(Value::Record(BTreeMap::from([(
"unknown".into(),
Value::String("value".into()),
)])))
.is_err()
);
assert!(Color::decode(Value::String("Green".into())).is_err());
assert!(Entry::new("articles/1").is_err());
assert!(Entry::decode(Value::String("/articles/../1".into())).is_err());
assert!(JsonValue::decode(Value::Bytes(vec![1])).is_err());
assert!(
JsonValue::decode(Value::Record(BTreeMap::from([(
"nested".into(),
Value::List(vec![Value::Bytes(vec![1])]),
)])))
.is_err()
);
assert!(Color::decode(Value::Enum("Green".into())).is_err());
}
crates/wip-interface/tests/interface.rs
+100 -53
View File
@@ -1,5 +1,10 @@
use wip_interface::wip_protocol::{NamedValue, TypeDeclaration, TypeExpr, Value};
use wip_interface::{DispatchError, HostError, OperationResult, WipType, interface};
use std::collections::BTreeMap;
use wip_interface::wip_protocol::{INTERFACE_FORMAT_V1, TypeExpr, Value};
use wip_interface::{
DispatchError, DispatchPhase, EffectGuarantee, HostError, HostErrorKind, OperationResult,
WipType, interface,
};
/// Publication request.
#[derive(Debug, Clone, PartialEq, WipType)]
@@ -36,7 +41,7 @@ pub trait Catalog {
note: Option<String>,
) -> OperationResult<PublishOutcome>;
/// Checks connectivity without returning an application value.
/// Checks connectivity without returning application data.
fn ping(&self) -> OperationResult<()>;
/// Demonstrates a host/runtime failure.
@@ -64,7 +69,10 @@ impl Catalog for AcceptingCatalog {
}
fn host_value(&self) -> OperationResult<String> {
Err(HostError::new("backend unavailable"))
Err(HostError::internal(
"backend unavailable",
EffectGuarantee::Unknown,
))
}
}
@@ -88,36 +96,49 @@ impl Catalog for RejectingCatalog {
}
}
fn named(name: &str, value: Value) -> NamedValue {
NamedValue {
name: name.into(),
value,
struct PanickingCatalog;
impl Catalog for PanickingCatalog {
fn publish(
&self,
_request: PublishRequest,
_note: Option<String>,
) -> OperationResult<PublishOutcome> {
panic!("private panic payload")
}
fn ping(&self) -> OperationResult<()> {
panic!("private panic payload")
}
fn host_value(&self) -> OperationResult<String> {
panic!("private panic payload")
}
}
fn publish_arguments(with_note: bool) -> Vec<NamedValue> {
let mut arguments = vec![named(
"request",
fn publish_arguments(with_note: bool) -> BTreeMap<String, Value> {
let mut arguments = BTreeMap::from([(
"request".into(),
PublishRequest {
title: "example".into(),
}
.encode()
.unwrap(),
)];
)]);
if with_note {
arguments.push(named("note", Value::String("audit".into())));
arguments.insert("note".into(), Value::String("audit".into()));
}
arguments
}
#[test]
fn descriptor_is_generated_only_from_the_trait_declaration() {
fn descriptor_is_canonical_and_generated_only_from_the_trait_declaration() {
let first = CatalogDefinition::descriptor();
let second = CatalogDefinition::descriptor();
assert_eq!(first, second);
first.validate().unwrap();
assert_eq!(first.name, "Catalog");
assert_eq!(first.format, INTERFACE_FORMAT_V1);
assert_eq!(
first.documentation.as_ref().unwrap().summary,
"Catalog editing capability."
@@ -139,84 +160,110 @@ fn descriptor_is_generated_only_from_the_trait_declaration() {
.summary,
"Item to publish."
);
assert!(!publish.parameters[0].optional);
assert!(publish.parameters[1].optional);
assert!(publish.parameters[0].required);
assert!(!publish.parameters[1].required);
assert_eq!(
publish
.returns
.as_ref()
.unwrap()
.documentation
.as_ref()
.unwrap()
.summary,
publish.returns.documentation.as_ref().unwrap().summary,
"The application publication outcome."
);
assert_eq!(
publish.returns.as_ref().unwrap().ty,
TypeExpr::Named("PublishOutcome".into())
publish.returns.r#type,
TypeExpr::Named {
name: "PublishOutcome".into(),
}
);
assert!(first.operations[1].returns.is_none());
assert_eq!(first.operations[1].returns.r#type, TypeExpr::Unit);
assert!(
first
.declarations
.types
.iter()
.any(|declaration| matches!(declaration, TypeDeclaration::Record(_)))
.any(|declaration| matches!(declaration.definition, TypeExpr::Record { .. }))
);
assert!(
first
.declarations
.types
.iter()
.any(|declaration| matches!(declaration, TypeDeclaration::Union(_)))
.any(|declaration| matches!(declaration.definition, TypeExpr::Union { .. }))
);
// Both implementation types satisfy the same generated dispatch boundary;
// neither can affect the descriptor shape.
// Both implementation types satisfy one immutable generated definition;
// implementation selection cannot contribute fields to the descriptor.
fn accepts_definition<T: Catalog>(_: &T) {}
accepts_definition(&AcceptingCatalog);
accepts_definition(&RejectingCatalog);
assert_eq!(CatalogDefinition::descriptor(), first);
}
#[test]
fn generated_argument_decoder_and_result_encoder_round_trip() {
fn generated_argument_decoder_and_result_encoder_use_raw_values() {
let decoded = CatalogPublishArguments::decode(publish_arguments(false)).unwrap();
assert_eq!(decoded.request.title, "example");
assert_eq!(decoded.note, None);
let encoded = CatalogPublishArguments::encode_result(PublishOutcome::Rejected("domain".into()))
.unwrap()
.unwrap();
let encoded =
CatalogPublishArguments::encode_result(PublishOutcome::Rejected("domain".into())).unwrap();
assert_eq!(
PublishOutcome::decode(encoded).unwrap(),
PublishOutcome::Rejected("domain".into())
);
assert_eq!(
CatalogPingArguments::encode_result(()).unwrap(),
Value::Unit
);
}
#[test]
fn typed_dispatch_validates_decodes_invokes_encodes_and_validates() {
let value = CatalogDefinition::dispatch(&AcceptingCatalog, "publish", publish_arguments(true))
.unwrap()
.unwrap();
let value =
CatalogDefinition::dispatch(&AcceptingCatalog, "publish", publish_arguments(true)).unwrap();
assert_eq!(
PublishOutcome::decode(value).unwrap(),
PublishOutcome::Published(true)
);
assert_eq!(
CatalogDefinition::dispatch(&AcceptingCatalog, "ping", vec![]).unwrap(),
None
CatalogDefinition::dispatch(&AcceptingCatalog, "ping", BTreeMap::new()).unwrap(),
Value::Unit
);
let invalid = CatalogDefinition::dispatch(&AcceptingCatalog, "publish", vec![]).unwrap_err();
let invalid =
CatalogDefinition::dispatch(&AcceptingCatalog, "publish", BTreeMap::new()).unwrap_err();
assert!(matches!(invalid, DispatchError::InvalidArguments(_)));
assert_eq!(invalid.phase(), DispatchPhase::BeforeInvocation);
assert_eq!(invalid.effect_guarantee(), None);
let host = CatalogDefinition::dispatch(&AcceptingCatalog, "host_value", vec![]).unwrap_err();
assert!(matches!(host, DispatchError::Host(error) if error.message() == "backend unavailable"));
let host =
CatalogDefinition::dispatch(&AcceptingCatalog, "host_value", BTreeMap::new()).unwrap_err();
assert!(
matches!(&host, DispatchError::Host(error) if error.message() == "backend unavailable")
);
assert_eq!(host.phase(), DispatchPhase::AfterInvocation);
assert_eq!(host.effect_guarantee(), Some(EffectGuarantee::Unknown));
let unknown = CatalogDefinition::dispatch(&AcceptingCatalog, "missing", vec![]).unwrap_err();
let panic =
CatalogDefinition::dispatch(&PanickingCatalog, "host_value", BTreeMap::new()).unwrap_err();
assert!(matches!(panic, DispatchError::Panic));
assert_eq!(panic.phase(), DispatchPhase::AfterInvocation);
assert_eq!(panic.effect_guarantee(), Some(EffectGuarantee::Unknown));
assert!(!panic.to_string().contains("private panic payload"));
let unknown =
CatalogDefinition::dispatch(&AcceptingCatalog, "missing", BTreeMap::new()).unwrap_err();
assert!(matches!(unknown, DispatchError::UnknownOperation(name) if name == "missing"));
}
#[test]
fn host_errors_require_a_typed_kind_and_effect_guarantee() {
let internal = HostError::internal("x".repeat(4_096), EffectGuarantee::NotCommitted);
assert_eq!(internal.kind(), HostErrorKind::Internal);
assert_eq!(internal.effect_guarantee(), EffectGuarantee::NotCommitted);
assert!(internal.message().len() <= 512);
let resource = HostError::resource_limit("deadline", EffectGuarantee::Unknown);
assert_eq!(resource.kind(), HostErrorKind::ResourceLimitExceeded);
assert_eq!(resource.effect_guarantee(), EffectGuarantee::Unknown);
}
/// Operations whose distinct source names normalize to the same PascalCase.
#[interface]
pub trait DistinctOperations {
@@ -245,12 +292,12 @@ fn distinct_operation_names_always_generate_distinct_public_items() {
assert_eq!(descriptor.operations[0].name, "item");
assert_eq!(descriptor.operations[1].name, "item_");
let first = DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item", vec![])
.unwrap()
.unwrap();
let second = DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item_", vec![])
.unwrap()
.unwrap();
let first =
DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item", BTreeMap::new())
.unwrap();
let second =
DistinctOperationsDefinition::dispatch(&DistinctImplementation, "item_", BTreeMap::new())
.unwrap();
assert_eq!(first, Value::String("item".into()));
assert_eq!(second, Value::String("item_".into()));
}
crates/wip-interface/tests/ui/mixed_enum.rs
+2 -2
View File
@@ -1,9 +1,9 @@
use wip_interface::WipType;
#[derive(WipType)]
enum MixedEnum {
enum UnsupportedEnum {
Empty,
Payload(String),
Payload { value: String },
}
fn main() {}
crates/wip-interface/tests/ui/mixed_enum.stderr
+4 -4
View File
@@ -1,5 +1,5 @@
error: a `WipType` enum must contain either only unit variants or only single-field tuple variants; mixed and named-field variants are unsupported
--> tests/ui/mixed_enum.rs:4:1
error: a `WipType` enum must contain unit variants and/or single-field tuple variants; named-field and multi-field variants are unsupported
--> tests/ui/mixed_enum.rs:6:5
|
4 | enum MixedEnum {
| ^^^^
6 | Payload { value: String },
| ^^^^^^^
crates/wip-interface/tests/ui/unsupported_type.stderr
+10 -20
View File
@@ -4,16 +4,11 @@ error[E0277]: the trait bound `(std::string::String, std::string::String): WipTy
5 | fn load(&self, pair: (String, String)) -> OperationResult<String>;
| ^^^^^^^^^^^^^^^^ the trait `WipType` is not implemented for `(std::string::String, std::string::String)`
|
= help: the following other types implement trait `WipType`:
JsonValue
Vec<T>
bool
f32
f64
i128
i16
i32
and $N others
help: the trait `WipType` is implemented for `()`
--> src/lib.rs
|
| impl WipType for () {
| ^^^^^^^^^^^^^^^^^^^
error[E0277]: the trait bound `(std::string::String, std::string::String): WipType` is not satisfied
--> tests/ui/unsupported_type.rs:5:26
@@ -24,16 +19,11 @@ error[E0277]: the trait bound `(std::string::String, std::string::String): WipTy
5 | fn load(&self, pair: (String, String)) -> OperationResult<String>;
| ^^^^^^^^^^^^^^^^ the trait `WipType` is not implemented for `(std::string::String, std::string::String)`
|
= help: the following other types implement trait `WipType`:
JsonValue
Vec<T>
bool
f32
f64
i128
i16
i32
and $N others
help: the trait `WipType` is implemented for `()`
--> src/lib.rs
|
| impl WipType for () {
| ^^^^^^^^^^^^^^^^^^^
note: required by a bound in `wip_interface::__private::RecordDecoder::required`
--> src/lib.rs
|
crates/wip-protocol/src/error.rs
+220 -86
View File
@@ -8,79 +8,65 @@ pub enum NameNamespace {
TypeDeclaration,
/// Operations in an interface descriptor.
Operation,
/// Fields in a record declaration.
/// Fields in an inline or named record type.
Field,
/// Parameters in an operation declaration.
Parameter,
/// Variants in an enum declaration.
EnumVariant,
/// Variants in a union declaration.
UnionVariant,
/// Fields supplied in a record value.
RecordValueField,
/// Arguments supplied in an operation call.
Argument,
/// Members in a logical JSON object.
JsonMember,
/// Descriptors in an interface observation.
InterfaceDescriptor,
/// Cases in an enum type.
EnumCase,
/// Cases in a union type.
UnionCase,
/// Child object names beneath one tree node.
ChildObject,
}
/// Structural kind of a logical protocol value.
/// Structural kind of a schema-neutral logical value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ValueKind {
/// String value.
String,
/// Unit value.
Unit,
/// Boolean value.
Boolean,
/// Integer value.
Integer,
/// Floating-point number value.
Number,
/// String value.
String,
/// Byte sequence.
Bytes,
/// List value.
List,
/// Key/value entry.
Entry,
/// Record value.
Record,
/// Enum value.
Enum,
/// Tagged-union value.
Union,
/// Logical JSON value.
Json,
/// List value.
List,
}
/// A typed segment identifying a declaration or value location.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PathSegment {
/// Interface descriptor.
Interface(String),
/// Descriptor root.
Descriptor,
/// Named type declaration.
Declaration(String),
/// Operation declaration or call.
Operation(String),
/// Record field declaration or value.
Field(String),
/// Operation parameter declaration or argument.
/// Operation parameter or argument.
Parameter(String),
/// Enum or union variant.
Variant(String),
/// List or JSON array index.
/// Enum or union case.
Case(String),
/// List index.
Index(usize),
/// Entry key.
EntryKey,
/// Entry value.
EntryValue,
/// Operation return value.
Return,
/// JSON object member.
JsonMember(String),
/// Object at a Worldspace path.
Object(String),
/// Child object in a tree response.
Child(String),
}
/// Machine-readable reason why protocol validation failed.
/// Machine-readable reason why logical protocol validation failed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ValidationErrorKind {
/// A name occurred more than once in one namespace.
@@ -117,11 +103,15 @@ pub enum ValidationErrorKind {
/// Missing field name.
name: String,
},
/// An enum or union value selected an undeclared variant.
UnknownVariant {
/// Unknown variant name.
/// An enum or union selected an undeclared case.
UnknownCase {
/// Unknown case name.
name: String,
},
/// A payload-bearing union case omitted `value`.
MissingUnionPayload,
/// A payload-free union case supplied `value`.
UnexpectedUnionPayload,
/// An operation call contains an undeclared argument.
UnknownParameter {
/// Unknown parameter name.
@@ -132,44 +122,66 @@ pub enum ValidationErrorKind {
/// Missing parameter name.
name: String,
},
/// An integer is outside the JavaScript-lossless range.
/// An operation is not declared by the descriptor.
UnknownOperation {
/// Unknown operation name.
name: String,
},
/// An integer is outside the interoperable safe range.
IntegerOutOfRange {
/// Rejected integer.
value: i64,
},
/// A numeric value is NaN or infinite.
NonFiniteNumber,
/// A JSON-interpreted value tree contains protocol bytes.
BytesInJson,
/// An object name is not a valid root or non-root path segment.
InvalidObjectName {
/// Rejected object name.
name: String,
},
/// An object's ordered interface set contains a duplicate.
DuplicateInterface {
/// Duplicate interface name.
name: String,
/// Duplicate opaque interface reference.
reference: String,
},
/// An observation omits a descriptor named by its object.
MissingInterfaceDescriptor {
/// Missing interface name.
name: String,
/// A string is not a canonical absolute Worldspace path.
InvalidPath {
/// Rejected path.
path: String,
},
/// An observation contains a descriptor not named by its object.
UnexpectedInterfaceDescriptor {
/// Unexpected interface name.
name: String,
},
/// A call targets an interface other than the descriptor being used.
InterfaceMismatch {
/// Descriptor interface name.
/// An object name does not match the path where it was observed.
ObjectNameMismatch {
/// Name required by the observation path.
expected: String,
/// Call target interface name.
/// Name supplied by the object.
actual: String,
},
/// An operation is not declared by the interface.
UnknownOperation {
/// Unknown operation name.
name: String,
/// Equivalent ref/validator observations disagree on object representation.
InconsistentObjectObservation {
/// Shared opaque object reference.
reference: String,
},
/// A `fetch_tree` request used a zero limit.
ZeroTreeLimit,
/// A tree response exceeds the requested maximum depth.
TreeDepthExceeded {
/// Requested maximum depth.
maximum: u32,
},
/// A tree response exceeds the requested maximum node count.
TreeLimitExceeded {
/// Requested maximum node count.
limit: u32,
},
/// A response refers to a different interface than its request.
InterfaceResponseMismatch {
/// Requested opaque reference.
expected: String,
/// Returned opaque reference.
actual: String,
},
/// A no-return operation produced a value.
UnexpectedReturnValue,
/// An operation with a return declaration produced no value.
MissingReturnValue,
}
/// A validation failure with a typed path to the failing location.
@@ -211,30 +223,152 @@ impl Display for ValidationError {
impl Error for ValidationError {}
/// Stable category of an error returned by a protocol host runtime.
/// One core interaction whose failure codes form a closed set.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProtocolErrorCategory {
/// The request is structurally invalid.
InvalidRequest,
/// The target object is not published.
ObjectNotFound,
/// The target interface is not implemented by the object.
InterfaceNotFound,
/// The target operation is not declared by the interface.
OperationNotFound,
/// Supplied operation arguments are invalid.
InvalidArguments,
/// The implementation rejected the call for a domain reason.
OperationFailed,
/// The host encountered an internal failure.
Internal,
pub enum ProtocolInteraction {
/// Fetch one object by its Worldspace path.
Fetch,
/// Fetch a bounded tree of objects.
FetchTree,
/// Fetch one interface descriptor by its opaque reference.
FetchInterface,
/// Invoke one operation on a path-targeted object.
CallOperation,
}
/// Transport-independent protocol failure returned by a host runtime.
/// Stable protocol failure code returned by a host.
///
/// This is the complete wire-level code set. A Client treats a malformed success
/// or failure response, including a code disallowed for its interaction, as a
/// Client-local `InvalidResponse`. An unsupported descriptor format is likewise
/// a Client-local `UnsupportedDescriptorFormat`; neither condition is a code a
/// Host can return.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProtocolErrorCode {
/// The request is structurally invalid before an operation descriptor is fixed.
InvalidRequest,
/// The target object is not published.
NotFound,
/// The interface reference is not currently published.
InterfaceNotFound,
/// The selected interface is not on the current object.
InterfaceMismatch,
/// The selected operation is not declared by the current interface.
OperationNotFound,
/// Supplied arguments do not match the fixed operation declaration.
InvalidArguments,
/// The operation requires an object validator and none was supplied.
ValidatorRequired,
/// The supplied object validator does not match current state.
ValidatorMismatch,
/// A mutable interface requires its validator and none was supplied.
InterfaceValidatorRequired,
/// The supplied interface validator does not match the descriptor.
InterfaceValidatorMismatch,
/// A published operation is not permitted for the caller.
PermissionDenied,
/// A bounded protocol resource limit was exceeded.
///
/// For `call_operation`, the Host guarantees that the operation was not run
/// or that all of its effects were rolled back.
ResourceLimitExceeded,
/// The Host encountered an internal failure.
///
/// For `call_operation`, the Host guarantees that the operation was not run
/// or that all of its effects were rolled back.
Internal,
/// The Host cannot guarantee that the operation was not run or rolled back.
///
/// A Client must not automatically retry because the operation may have
/// committed effects even though no success response was available.
OperationOutcomeUnknown,
}
impl ProtocolErrorCode {
/// Every canonical wire-level error code.
pub const ALL: [Self; 14] = [
Self::InvalidRequest,
Self::NotFound,
Self::InterfaceNotFound,
Self::InterfaceMismatch,
Self::OperationNotFound,
Self::InvalidArguments,
Self::ValidatorRequired,
Self::ValidatorMismatch,
Self::InterfaceValidatorRequired,
Self::InterfaceValidatorMismatch,
Self::PermissionDenied,
Self::ResourceLimitExceeded,
Self::Internal,
Self::OperationOutcomeUnknown,
];
/// Whether a Host may return this code for `interaction`.
///
/// `false` identifies an invalid error response; it does not turn that
/// response into another wire-level protocol failure.
#[must_use]
pub const fn is_allowed_for(self, interaction: ProtocolInteraction) -> bool {
use ProtocolErrorCode::{
InterfaceMismatch, InterfaceNotFound, InterfaceValidatorMismatch,
InterfaceValidatorRequired, Internal, InvalidArguments, InvalidRequest, NotFound,
OperationNotFound, OperationOutcomeUnknown, PermissionDenied, ResourceLimitExceeded,
ValidatorMismatch, ValidatorRequired,
};
use ProtocolInteraction::{CallOperation, Fetch, FetchInterface, FetchTree};
match (interaction, self) {
(_, InvalidRequest | ResourceLimitExceeded | Internal) => true,
(Fetch | FetchTree, NotFound) => true,
(FetchInterface, InterfaceNotFound) => true,
(
CallOperation,
NotFound
| InterfaceMismatch
| OperationNotFound
| InvalidArguments
| ValidatorRequired
| ValidatorMismatch
| InterfaceValidatorRequired
| InterfaceValidatorMismatch
| PermissionDenied
| OperationOutcomeUnknown,
) => true,
(
_,
NotFound
| InterfaceNotFound
| InterfaceMismatch
| OperationNotFound
| InvalidArguments
| ValidatorRequired
| ValidatorMismatch
| InterfaceValidatorRequired
| InterfaceValidatorMismatch
| PermissionDenied
| OperationOutcomeUnknown,
) => false,
}
}
}
/// Transport-independent protocol failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProtocolError {
/// Stable programmatic category.
pub category: ProtocolErrorCategory,
/// Human-readable diagnostic. Consumers must not branch on this text.
/// Stable programmatic code. Consumers must branch on this field.
pub code: ProtocolErrorCode,
/// Bounded human-readable diagnostic. Consumers must not branch on it.
pub message: String,
}
impl Display for ProtocolError {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
write!(
formatter,
"protocol failure ({:?}): {}",
self.code, self.message
)
}
}
impl Error for ProtocolError {}
crates/wip-protocol/src/lib.rs
+64 -14
View File
@@ -1,9 +1,45 @@
//! Transport-independent logical types for the Web Interface Protocol (WIP).
//! Canonical transport-independent logical types for the Web Interface Protocol.
//!
//! This crate deliberately models interface declarations, published objects,
//! operation calls, and operation results without assigning them HTTP routes,
//! methods, headers, or JSON envelopes. A transport can encode these values,
//! but the encoding is outside this crate's contract.
//! This crate follows the Core Model and `3-protocol.md` without assigning HTTP
//! routes, methods, headers, URL encodings, or JSON envelopes. The correspondence
//! between canonical logical concepts and this crate is direct:
//!
//! | Canonical protocol concept | Rust API |
//! | --- | --- |
//! | Object projection and ordered interface set | [`Object`] |
//! | Optional object identity / state precondition | `Object::ref` / [`Object::validator`] |
//! | Interface Descriptor | [`InterfaceDescriptor`] |
//! | Named declaration and all schema expressions | [`TypeDeclaration`] / [`TypeExpr`] |
//! | Schema-neutral primitive/composite value | [`Value`] |
//! | `fetch` | [`FetchRequest`] / [`FetchResponse`] |
//! | `fetch_tree` | [`FetchTreeRequest`] / [`FetchTreeResponse`] |
//! | `fetch_interface` | [`FetchInterfaceRequest`] / [`FetchInterfaceResponse`] |
//! | Object and interface call preconditions | [`Target`] / [`InterfaceTarget`] |
//! | `call_operation` | [`CallOperationRequest`] / [`CallOperationResponse`] |
//! | Stable Host failure taxonomy | [`ProtocolErrorCode`] / [`ProtocolError`] |
//! | Per-interaction allowed failure codes | [`ProtocolInteraction`] / [`ProtocolErrorCode::is_allowed_for`] |
//!
//! [`ProtocolErrorCode`] is a closed set of Host-returned wire failures. After a
//! Client receives a response, an invalid Object, Descriptor, operation result,
//! malformed error, or error code disallowed by [`ProtocolInteraction`] is a
//! Client-local `InvalidResponse`, not another wire error. A descriptor whose
//! `format` is not supported is a Client-local `UnsupportedDescriptorFormat`.
//!
//! For `call_operation`, [`ProtocolErrorCode::Internal`] and
//! [`ProtocolErrorCode::ResourceLimitExceeded`] guarantee that the operation did
//! not run or that all effects were rolled back. Only
//! [`ProtocolErrorCode::OperationOutcomeUnknown`] means the Host cannot make that
//! guarantee; Clients must not automatically retry it.
//!
//! Paths, object refs, interface refs, and validators remain separate concepts.
//! They are represented by ordinary protocol strings/bytes in the corresponding
//! fields. In particular, object refs are optional, operation targeting uses a
//! path, and this crate defines no interaction that fetches an object by ref.
//!
//! [`Value`] contains only the canonical raw value kinds. A descriptor interprets
//! enum values as strings, entries as canonical-path strings, and unions as
//! records with a `$case` string plus an optional `value` payload. JSON uses the
//! same value tree (`Unit` is JSON null) and rejects bytes.
#![deny(missing_docs)]
@@ -12,19 +48,33 @@ mod model;
mod validation;
pub use error::{
NameNamespace, PathSegment, ProtocolError, ProtocolErrorCategory, ValidationError,
ValidationErrorKind, ValueKind,
NameNamespace, PathSegment, ProtocolError, ProtocolErrorCode, ProtocolInteraction,
ValidationError, ValidationErrorKind, ValueKind,
};
pub use model::{
Documentation, EnumDeclaration, EnumVariantDeclaration, FieldDeclaration, InterfaceDescriptor,
InterfaceObservation, JsonMember, JsonValue, NamedValue, Object, ObjectId, OperationCall,
OperationDeclaration, OperationOutcome, OperationResult, OperationTarget, ParameterDeclaration,
RecordDeclaration, ReturnDeclaration, TypeDeclaration, TypeExpr, UnionDeclaration,
UnionVariantDeclaration, Value,
CallOperationRequest, CallOperationResponse, Documentation, EnumCase, FetchInterfaceRequest,
FetchInterfaceResponse, FetchRequest, FetchResponse, FetchTreeRequest, FetchTreeResponse,
FieldDeclaration, InterfaceDescriptor, InterfaceTarget, Object, ObjectTreeNode,
OperationDeclaration, ParameterDeclaration, ProtocolResult, ReturnDeclaration, Target,
TypeDeclaration, TypeExpr, UnionCase, Value,
};
/// Largest integer that is exactly interoperable with a JavaScript `Number`.
/// Validates a canonical absolute Worldspace path.
pub fn validate_path(path: &str) -> Result<(), ValidationError> {
validation::validate_path(path)
}
/// Canonical format identifier for the first Interface Descriptor format.
pub const INTERFACE_FORMAT_V1: &str = "wip-interface/1";
/// Discriminator field used by a union's raw record value.
pub const UNION_CASE_FIELD: &str = "$case";
/// Optional payload field used by a union's raw record value.
pub const UNION_VALUE_FIELD: &str = "value";
/// Largest integer exactly interoperable with a JavaScript `Number`.
pub const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
/// Smallest integer that is exactly interoperable with a JavaScript `Number`.
/// Smallest integer exactly interoperable with a JavaScript `Number`.
pub const MIN_SAFE_INTEGER: i64 = -MAX_SAFE_INTEGER;
crates/wip-protocol/src/model.rs
+308 -253
View File
@@ -1,6 +1,8 @@
use std::collections::BTreeMap;
use crate::{ProtocolError, ValidationError};
/// Human-readable documentation attached to a protocol declaration.
/// Human-readable plain-text documentation attached to a protocol declaration.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Documentation {
/// A short, self-contained description.
@@ -9,242 +11,194 @@ pub struct Documentation {
pub details: Option<String>,
}
/// Stable logical identity of a published object.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ObjectId(pub String);
/// A published object and the ordered set of interfaces it implements.
/// The protocol projection currently published at one Worldspace path.
///
/// The vector order is significant. Call [`Object::validate`] before
/// publication to reject duplicate interface names.
/// `name` is a path segment, `interfaces` is an ordered set of opaque interface
/// references, `r#ref` is optional object identity, and `validator` is an
/// independent optional observation precondition. In particular, neither the
/// path nor `r#ref` is a mandatory object identifier.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Object {
/// Logical object identity.
pub id: ObjectId,
/// Interface names in publication order.
/// Path-segment name. The root object's name is empty.
pub name: String,
/// Short public description of the object.
pub description: Option<String>,
/// Opaque interface references in host publication order.
pub interfaces: Vec<String>,
}
/// A complete logical observation of an object and its interface descriptors.
#[derive(Debug, Clone, PartialEq)]
pub struct InterfaceObservation {
/// Observed object.
pub object: Object,
/// Descriptors corresponding to `object.interfaces`.
pub descriptors: Vec<InterfaceDescriptor>,
/// Optional opaque identity within one client-facing Worldspace.
pub r#ref: Option<String>,
/// Optional opaque validator for the object's observed state.
pub validator: Option<Vec<u8>>,
}
/// Transport-independent description of one interface.
#[derive(Debug, Clone, PartialEq)]
///
/// Interface identity is supplied by interaction fields such as
/// [`FetchInterfaceResponse::interface`], not embedded in the descriptor.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InterfaceDescriptor {
/// Interface name.
pub name: String,
/// Descriptor format version understood by clients and hosts.
pub format: String,
/// Optional interface documentation.
pub documentation: Option<Documentation>,
/// Named type declarations local to this descriptor.
pub declarations: Vec<TypeDeclaration>,
/// Named declarations local to this descriptor.
pub types: Vec<TypeDeclaration>,
/// Operations exposed by this interface.
pub operations: Vec<OperationDeclaration>,
}
/// A named type declaration local to an interface descriptor.
#[derive(Debug, Clone, PartialEq)]
pub enum TypeDeclaration {
/// A record declaration.
Record(RecordDeclaration),
/// An enumeration declaration.
Enum(EnumDeclaration),
/// A tagged union declaration.
Union(UnionDeclaration),
}
impl TypeDeclaration {
/// Returns the descriptor-local declaration name.
#[must_use]
pub fn name(&self) -> &str {
match self {
Self::Record(declaration) => &declaration.name,
Self::Enum(declaration) => &declaration.name,
Self::Union(declaration) => &declaration.name,
}
}
}
/// Declaration of a record with named fields.
#[derive(Debug, Clone, PartialEq)]
pub struct RecordDeclaration {
/// A descriptor-local named type declaration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDeclaration {
/// Descriptor-local type name.
pub name: String,
/// Optional record documentation.
/// Optional type documentation.
pub documentation: Option<Documentation>,
/// Fields in declaration order.
pub fields: Vec<FieldDeclaration>,
/// Definition associated with `name`.
pub definition: TypeExpr,
}
/// A type expression used by declarations, fields, parameters, and returns.
///
/// [`TypeExpr::Named`] references are resolved only within the containing
/// descriptor. Recursive references, including recursion through lists,
/// records, and unions, are invalid.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TypeExpr {
/// A value carrying no data.
Unit,
/// A boolean.
Boolean,
/// A JavaScript-lossless signed integer.
Integer,
/// A finite IEEE-754 binary64 number.
Number,
/// A Unicode string.
String,
/// An opaque byte sequence.
Bytes,
/// A schema-opaque JSON-compatible value tree.
Json,
/// A canonical absolute Worldspace path represented by a string value.
Entry,
/// A descriptor-local named declaration.
Named {
/// Referenced declaration name.
name: String,
},
/// A record with named fields.
Record {
/// Fields in declaration order.
fields: Vec<FieldDeclaration>,
},
/// An ordered list.
List {
/// Type of every list item.
items: Box<TypeExpr>,
},
/// A closed set of payload-free cases represented by strings.
Enum {
/// Cases in declaration order.
cases: Vec<EnumCase>,
},
/// A discriminated union represented by a record.
Union {
/// Cases in declaration order.
cases: Vec<UnionCase>,
},
}
/// Declaration of a record field.
#[derive(Debug, Clone, PartialEq)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FieldDeclaration {
/// Field name.
pub name: String,
/// Whether the field must be present.
pub required: bool,
/// Optional field documentation.
pub documentation: Option<Documentation>,
/// Field value type.
pub ty: TypeExpr,
/// Whether the field may be omitted.
///
/// Optionality represents absence, not a `null` value.
pub optional: bool,
pub r#type: TypeExpr,
}
/// Declaration of an enumeration.
/// One payload-free enum case.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EnumDeclaration {
/// Descriptor-local type name.
pub struct EnumCase {
/// Case name.
pub name: String,
/// Optional enum documentation.
/// Optional case documentation.
pub documentation: Option<Documentation>,
/// Allowed variants in declaration order.
pub variants: Vec<EnumVariantDeclaration>,
}
/// Declaration of one enumeration variant.
/// One union case with zero or one payload.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EnumVariantDeclaration {
/// Variant name.
pub struct UnionCase {
/// Case name.
pub name: String,
/// Optional variant documentation.
/// Optional case documentation.
pub documentation: Option<Documentation>,
}
/// Declaration of a tagged union.
#[derive(Debug, Clone, PartialEq)]
pub struct UnionDeclaration {
/// Descriptor-local type name.
pub name: String,
/// Optional union documentation.
pub documentation: Option<Documentation>,
/// Allowed tagged variants in declaration order.
pub variants: Vec<UnionVariantDeclaration>,
}
/// Declaration of one tagged-union variant.
#[derive(Debug, Clone, PartialEq)]
pub struct UnionVariantDeclaration {
/// Variant tag.
pub name: String,
/// Optional variant documentation.
pub documentation: Option<Documentation>,
/// Payload type.
pub ty: TypeExpr,
}
/// A type expression used by fields, parameters, returns, and union payloads.
///
/// `Named` references are resolved only within the containing descriptor.
/// Optional values are represented by the containing field or parameter and
/// therefore are intentionally not a type expression.
#[derive(Debug, Clone, PartialEq)]
pub enum TypeExpr {
/// A UTF-8 string.
String,
/// A boolean.
Boolean,
/// A JavaScript-lossless integer.
Integer,
/// A finite IEEE-754 double precision number.
Number,
/// An opaque byte sequence.
Bytes,
/// An ordered sequence of values.
List(Box<TypeExpr>),
/// A key/value entry.
Entry {
/// Entry key type.
key: Box<TypeExpr>,
/// Entry value type.
value: Box<TypeExpr>,
},
/// A logical JSON value.
Json,
/// A descriptor-local named declaration.
Named(String),
/// Optional payload type.
pub payload: Option<TypeExpr>,
}
/// Declaration of one interface operation.
#[derive(Debug, Clone, PartialEq)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OperationDeclaration {
/// Operation name, unique within its interface.
/// Operation name, unique within its descriptor.
pub name: String,
/// Optional operation documentation.
pub documentation: Option<Documentation>,
/// Parameters in declaration order.
pub parameters: Vec<ParameterDeclaration>,
/// Return declaration, or `None` for an operation with no return value.
pub returns: Option<ReturnDeclaration>,
/// Return declaration. No-data operations return [`TypeExpr::Unit`].
pub returns: ReturnDeclaration,
}
/// Declaration of one operation parameter.
#[derive(Debug, Clone, PartialEq)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParameterDeclaration {
/// Parameter name.
pub name: String,
/// Whether the parameter must be present.
pub required: bool,
/// Optional parameter documentation.
pub documentation: Option<Documentation>,
/// Parameter value type.
pub ty: TypeExpr,
/// Whether the parameter may be omitted.
///
/// Optionality represents absence, not a `null` value.
pub optional: bool,
pub r#type: TypeExpr,
}
/// Declaration of an operation return value.
#[derive(Debug, Clone, PartialEq)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReturnDeclaration {
/// Optional return-value documentation.
pub documentation: Option<Documentation>,
/// Return value type.
pub ty: TypeExpr,
pub r#type: TypeExpr,
}
/// A logical protocol value.
/// A schema-neutral logical protocol value.
///
/// There is no general `Null` variant: optional record fields and operation
/// parameters are omitted. JSON null remains available inside [`Value::Json`].
/// Enum cases, union cases, entries, and JSON are interpretations imposed by a
/// descriptor. They are deliberately not variants of this enum. Record key
/// ordering is not protocol-significant.
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
/// A UTF-8 string.
String(String),
/// A value carrying no data; it also represents JSON null under `Json`.
Unit,
/// A boolean.
Boolean(bool),
/// An integer, validated against the JavaScript safe integer range.
/// A JavaScript-lossless integer.
Integer(i64),
/// A number, validated to be finite.
/// A finite IEEE-754 binary64 number.
Number(f64),
/// A Unicode string.
String(String),
/// An opaque byte sequence.
Bytes(Vec<u8>),
/// String-keyed fields with order-insensitive semantics.
Record(BTreeMap<String, Value>),
/// An ordered sequence.
List(Vec<Value>),
/// A key/value entry.
Entry {
/// Entry key.
key: Box<Value>,
/// Entry value.
value: Box<Value>,
},
/// Record fields. Duplicate names are invalid.
Record(Vec<NamedValue>),
/// An enum variant name.
Enum(String),
/// A tagged-union value.
Union {
/// Selected variant tag.
variant: String,
/// Variant payload.
value: Box<Value>,
},
/// A logical JSON value.
Json(JsonValue),
}
impl Value {
@@ -252,132 +206,233 @@ impl Value {
#[must_use]
pub fn kind(&self) -> crate::ValueKind {
match self {
Self::String(_) => crate::ValueKind::String,
Self::Unit => crate::ValueKind::Unit,
Self::Boolean(_) => crate::ValueKind::Boolean,
Self::Integer(_) => crate::ValueKind::Integer,
Self::Number(_) => crate::ValueKind::Number,
Self::String(_) => crate::ValueKind::String,
Self::Bytes(_) => crate::ValueKind::Bytes,
Self::List(_) => crate::ValueKind::List,
Self::Entry { .. } => crate::ValueKind::Entry,
Self::Record(_) => crate::ValueKind::Record,
Self::Enum(_) => crate::ValueKind::Enum,
Self::Union { .. } => crate::ValueKind::Union,
Self::Json(_) => crate::ValueKind::Json,
Self::List(_) => crate::ValueKind::List,
}
}
}
/// A named value used by records and operation arguments.
#[derive(Debug, Clone, PartialEq)]
pub struct NamedValue {
/// Field or parameter name.
pub name: String,
/// Associated value.
pub value: Value,
}
/// A transport-independent JSON value.
#[derive(Debug, Clone, PartialEq)]
pub enum JsonValue {
/// JSON null.
Null,
/// JSON boolean.
Boolean(bool),
/// JSON integer, validated against the JavaScript safe integer range.
Integer(i64),
/// JSON number, validated to be finite.
Number(f64),
/// JSON string.
String(String),
/// JSON array.
Array(Vec<JsonValue>),
/// JSON object. Duplicate member names are invalid.
Object(Vec<JsonMember>),
}
/// A member of a logical JSON object.
#[derive(Debug, Clone, PartialEq)]
pub struct JsonMember {
/// Member name.
pub name: String,
/// Member value.
pub value: JsonValue,
}
/// Logical destination of an operation call.
/// Request for the object currently published at one path.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OperationTarget {
/// Target object.
pub object: ObjectId,
/// Target interface name.
pub struct FetchRequest {
/// Canonical absolute Worldspace path.
pub path: String,
}
/// Successful `fetch` response.
pub type FetchResponse = Object;
/// Request for a bounded breadth-first object-tree observation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FetchTreeRequest {
/// Canonical absolute path of the tree root.
pub path: String,
/// Maximum depth, where the requested object has depth zero.
pub depth: u32,
/// Maximum total node count, including the root. Must be nonzero.
pub limit: u32,
}
/// One node in a tree observation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ObjectTreeNode {
/// Object observed at this tree position.
pub object: Object,
/// Direct children in host-defined traversal order.
pub children: Vec<ObjectTreeNode>,
}
/// Successful `fetch_tree` response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FetchTreeResponse {
/// Observed tree rooted at the requested path.
pub root: ObjectTreeNode,
/// Whether public indexable children were omitted by depth or limit.
pub truncated: bool,
}
/// Request for the current descriptor of one opaque interface reference.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FetchInterfaceRequest {
/// Opaque interface reference obtained from an object.
pub interface: String,
/// Target operation name.
}
/// Successful `fetch_interface` response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FetchInterfaceResponse {
/// Opaque interface reference corresponding to the request.
pub interface: String,
/// Current validated descriptor.
pub descriptor: InterfaceDescriptor,
/// Optional opaque validator for this descriptor observation.
pub validator: Option<Vec<u8>>,
}
/// Object portion of an operation target.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Target {
/// Canonical absolute path of the target object.
pub path: String,
/// Optional validator copied from the object observation.
pub validator: Option<Vec<u8>>,
}
/// Interface portion of an operation target.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InterfaceTarget {
/// Opaque interface reference selected from the object's interface set.
pub reference: String,
/// Optional validator copied from the interface observation.
pub validator: Option<Vec<u8>>,
}
/// Transport-independent request to execute one operation.
#[derive(Debug, Clone, PartialEq)]
pub struct CallOperationRequest {
/// Path and optional object-state precondition.
pub target: Target,
/// Interface reference and its independent optional precondition.
pub interface: InterfaceTarget,
/// Operation name within the selected descriptor.
pub operation: String,
/// Named arguments; map iteration order has no protocol meaning.
pub arguments: BTreeMap<String, Value>,
}
/// A transport-independent operation call.
/// Successful operation response.
#[derive(Debug, Clone, PartialEq)]
pub struct OperationCall {
/// Logical call target.
pub target: OperationTarget,
/// Named arguments. Optional arguments are represented by omission.
pub arguments: Vec<NamedValue>,
pub struct CallOperationResponse {
/// Application result validated against the operation return declaration.
pub result: Value,
/// Optional validator for the object state observed after execution.
pub validator: Option<Vec<u8>>,
}
/// Successful or failed logical outcome of an operation.
#[derive(Debug, Clone, PartialEq)]
pub enum OperationOutcome {
/// Operation returned. `None` represents a declared no-return operation.
Returned(Option<Value>),
/// Operation failed with a protocol-level error.
Failed(ProtocolError),
}
/// A transport-independent operation result.
#[derive(Debug, Clone, PartialEq)]
pub struct OperationResult {
/// Target corresponding to the result.
pub target: OperationTarget,
/// Logical outcome.
pub outcome: OperationOutcome,
/// Logical outcome of any core interaction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProtocolResult<T> {
/// The interaction succeeded.
Success(T),
/// The interaction failed at the protocol boundary.
Failure(ProtocolError),
}
impl Object {
/// Validates ordered-set interface semantics.
/// Validates the object-independent name and ordered-interface-set rules.
pub fn validate(&self) -> Result<(), ValidationError> {
crate::validation::validate_object(self)
}
}
impl InterfaceObservation {
/// Validates the object, descriptor structure, and their correspondence.
pub fn validate(&self) -> Result<(), ValidationError> {
crate::validation::validate_observation(self)
/// Validates this object as the response observed at `path`.
pub fn validate_at_path(&self, path: &str) -> Result<(), ValidationError> {
crate::validation::validate_object_at_path(self, path)
}
/// Validates equal representations for a shared ref and present validator.
pub fn validate_consistency_with(&self, other: &Self) -> Result<(), ValidationError> {
crate::validation::validate_object_consistency(self, other)
}
}
impl InterfaceDescriptor {
/// Validates declaration structure, references, and absence of recursion.
/// Validates declaration structure, named references, and absence of cycles.
pub fn validate(&self) -> Result<(), ValidationError> {
crate::validation::validate_descriptor(self)
}
/// Validates a value against a type expression in this descriptor.
pub fn validate_value(&self, ty: &TypeExpr, value: &Value) -> Result<(), ValidationError> {
crate::validation::validate_root_value(self, ty, value)
/// Validates a raw value against a type expression in this descriptor.
pub fn validate_value(&self, r#type: &TypeExpr, value: &Value) -> Result<(), ValidationError> {
crate::validation::validate_root_value(self, r#type, value)
}
/// Validates a call target and arguments against this descriptor.
pub fn validate_call(&self, call: &OperationCall) -> Result<(), ValidationError> {
crate::validation::validate_call(self, call)
}
/// Validates an operation's returned value against this descriptor.
pub fn validate_return(
/// Validates named arguments for one declared operation.
pub fn validate_arguments(
&self,
operation: &str,
value: Option<&Value>,
arguments: &BTreeMap<String, Value>,
) -> Result<(), ValidationError> {
crate::validation::validate_return(self, operation, value)
crate::validation::validate_arguments(self, operation, arguments)
}
/// Validates one operation result against its return declaration.
pub fn validate_result(&self, operation: &str, result: &Value) -> Result<(), ValidationError> {
crate::validation::validate_result(self, operation, result)
}
/// Validates the path, operation, and arguments in a call request.
pub fn validate_call(&self, request: &CallOperationRequest) -> Result<(), ValidationError> {
crate::validation::validate_call(self, request)
}
}
impl FetchRequest {
/// Validates the request path.
pub fn validate(&self) -> Result<(), ValidationError> {
crate::validation::validate_path(&self.path)
}
/// Validates an object returned for this request.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`].
pub fn validate_response(&self, response: &FetchResponse) -> Result<(), ValidationError> {
response.validate_at_path(&self.path)
}
}
impl FetchTreeRequest {
/// Validates the request path and nonzero node limit.
pub fn validate(&self) -> Result<(), ValidationError> {
crate::validation::validate_fetch_tree_request(self)
}
}
impl FetchTreeResponse {
/// Validates tree shape, names, depth, and node limit for `request`.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`].
pub fn validate_for(&self, request: &FetchTreeRequest) -> Result<(), ValidationError> {
crate::validation::validate_fetch_tree_response(self, request)
}
}
impl FetchInterfaceResponse {
/// Validates request correspondence and descriptor semantics.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`]. Descriptor format support is a
/// separate Client concern: an otherwise valid descriptor with an unsupported
/// `format` is a Client-local `UnsupportedDescriptorFormat`.
pub fn validate_for(&self, request: &FetchInterfaceRequest) -> Result<(), ValidationError> {
crate::validation::validate_fetch_interface_response(self, request)
}
}
impl CallOperationRequest {
/// Validates this call against the descriptor selected by `interface`.
pub fn validate_with(&self, descriptor: &InterfaceDescriptor) -> Result<(), ValidationError> {
descriptor.validate_call(self)
}
}
impl CallOperationResponse {
/// Validates this result against the named operation in `descriptor`.
///
/// Failure means the Client received an invalid success response; it is not a
/// Host-returned [`crate::ProtocolErrorCode`].
pub fn validate_for(
&self,
descriptor: &InterfaceDescriptor,
operation: &str,
) -> Result<(), ValidationError> {
descriptor.validate_result(operation, &self.result)
}
}
crates/wip-protocol/src/validation.rs
+452 -377
View File
File diff suppressed because it is too large Load Diff
crates/wip-protocol/tests/validation.rs
+729 -406
View File
File diff suppressed because it is too large Load Diff
crates/wip-public-api-example/Cargo.toml
+12
View File
@@ -0,0 +1,12 @@
[package]
name = "wip-public-api-example"
version = "0.1.0"
edition = "2024"
description = "Public-only end-to-end conformance consumer for the WIP Rust APIs"
license = "MIT OR Apache-2.0"
publish = false
[dependencies]
wip-host = { path = "../wip-host" }
wip-interface = { path = "../wip-interface" }
wip-protocol = { path = "../wip-protocol" }
crates/wip-public-api-example/src/lib.rs
+541
View File
@@ -0,0 +1,541 @@
//! Public-only conformance consumer for the WIP Rust crates.
//!
//! # Architectural boundary
//!
//! This package is an ordinary application consumer. Its direct dependencies are
//! the public `wip-protocol`, `wip-interface`, and `wip-host` crates; it neither
//! imports workspace-private modules nor depends on `wip-interface-macros`.
//! `wip-protocol` owns transport-independent DTOs and schema-neutral values,
//! while this package owns its application DTOs and interface traits. The
//! request-scoped implementation, backend handle, authorization policy, and
//! publication wiring remain host-private. A transport binding would translate
//! its own wire routes and envelopes to the protocol call DTOs; no HTTP type is
//! part of an application trait or interface descriptor.
//!
//! # Breaking migration exercised here
//!
//! The canonical API targets operations by `target.path` rather than a mandatory
//! object identifier. Object `ref` and object/interface validators are separate,
//! optional observation fields. Interface references are opaque values observed
//! separately from descriptors, and descriptors contain neither a Rust trait
//! name nor an opaque-reference `name` field. Application records, enums,
//! unions, entry paths, and JSON all encode through the schema-neutral [`Value`]
//! variants: entries and enums are strings, unions are discriminator records,
//! and JSON recursively uses ordinary records/lists/primitives. The former
//! `Entry<K, V>` and semantic `Value::Entry`, `Value::Enum`, `Value::Union`, and
//! `Value::Json` forms are intentionally unsupported.
//!
//! # Supported authoring subset
//!
//! Public, non-generic traits use immutable `&self` receivers, owned named
//! parameters, and explicit `wip::OperationResult<T>` returns. Derived DTOs are
//! named-field records, all-unit enums, or unions with unit and single-payload
//! cases. A direct `Option<T>` means field/argument omission, never protocol
//! null. See `wip-interface` for the complete rejected-syntax list.
#![deny(missing_docs)]
use std::collections::BTreeMap;
use std::error::Error;
use std::io;
use wip_host::{
CallErrorKind, CallRequest, ExecutionContext, InterfaceRef, InterfaceRegistry, InterfaceTarget,
ObjectProvider, ProviderResult, PublishedObject, RegisteredInterface, Target, Validator,
WipObject,
};
use wip_interface as wip;
use wip_interface::WipType;
use wip_protocol::{ProtocolError, ProtocolErrorCode, Value};
const OBJECT_PATH: &str = "/article-service";
const OBJECT_VALIDATOR: &[u8] = b"object-v1";
const CATALOG_VALIDATOR: &[u8] = b"catalog-v1";
/// Publication visibility represented as a protocol enum string.
#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
pub enum Visibility {
/// Visible to every authorized caller.
Public,
/// Visible only inside the application domain.
Private,
}
/// An application-owned request DTO mapped to a protocol record.
#[derive(Debug, Clone, PartialEq, wip::WipType)]
pub struct PublishRequest {
/// Title of the article to publish.
pub title: String,
/// Optional article body; omission is distinct from JSON null.
pub body: Option<String>,
/// Canonical Worldspace path to the source entry.
pub source: wip::Entry,
/// Application enum represented by a schema-neutral string.
pub visibility: Visibility,
/// Schema-opaque JSON represented by ordinary protocol values.
pub metadata: wip::JsonValue,
}
/// The application domain result of a publication attempt.
#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
pub enum PublishOutcome {
/// Publication succeeded and returned its application identifier.
Published(String),
/// An application policy rejected the publication.
Rejected(String),
}
/// Article publication operations.
#[wip::interface]
pub trait Catalog {
/// Publishes an article or reports an application-domain rejection.
///
/// # Returns
/// The typed application outcome.
fn publish(
&self,
/// Application publication request.
request: PublishRequest,
) -> wip::OperationResult<PublishOutcome>;
/// Returns the catalog-qualified status.
fn status(&self) -> wip::OperationResult<String>;
/// Demonstrates a rollback-confirmed host/backend failure.
fn backend_status(&self) -> wip::OperationResult<String>;
/// Demonstrates a host/backend failure with an unknown operation outcome.
fn uncertain_backend_status(&self) -> wip::OperationResult<String>;
/// Demonstrates denial after every structural precondition succeeds.
fn restricted_status(&self) -> wip::OperationResult<String>;
}
/// Audit operations exposed by the same object.
#[wip::interface]
pub trait Audit {
/// Returns the audit-qualified status.
fn status(&self) -> wip::OperationResult<String>;
}
/// A registered but deliberately unexposed interface.
#[wip::interface]
pub trait Diagnostics {
/// Returns host-private diagnostics when explicitly exposed.
fn diagnostics(&self) -> wip::OperationResult<String>;
}
/// Observable outcomes from the complete public-API scenario.
#[derive(Debug, Clone, PartialEq)]
pub struct DemoReport {
/// Path-segment name from the canonical object projection.
pub object_name: String,
/// Optional object identity, distinct from the resolution path.
pub object_reference: Option<String>,
/// Optional object-state validator.
pub object_validator: Option<Vec<u8>>,
/// Opaque interface references published by the object, in exposure order.
pub published_interfaces: Vec<String>,
/// Opaque reference assigned to the catalog descriptor.
pub catalog_interface_reference: String,
/// Opaque reference assigned to the audit descriptor.
pub audit_interface_reference: String,
/// Descriptor format observed separately for the catalog reference.
pub catalog_descriptor_format: String,
/// Descriptor format observed separately for the audit reference.
pub audit_descriptor_format: String,
/// Typed successful application result decoded from a validated [`Value`].
pub published: PublishOutcome,
/// Typed application-domain rejection decoded from a validated [`Value`].
pub rejected: PublishOutcome,
/// Result of the catalog-qualified `status` operation.
pub catalog_status: String,
/// Result of the audit-qualified `status` operation.
pub audit_status: String,
/// Stable failure kind produced by the deliberate host/backend failure.
pub host_failure: CallErrorKind,
/// Protocol failure whose operation effects are guaranteed not committed.
pub protocol_failure: ProtocolError,
/// Protocol failure whose operation effects cannot be proven absent.
pub unknown_protocol_failure: ProtocolError,
/// Authorization failure after a fully qualified valid request.
pub permission_failure: ProtocolErrorCode,
/// Recovery signal for a stale object validator.
pub validator_failure: ProtocolErrorCode,
/// Failure for a known but unexposed interface reference.
pub interface_mismatch: ProtocolErrorCode,
/// Failure for an unknown interface observation reference.
pub interface_not_found: ProtocolErrorCode,
/// First failure for a request with an invalid path and later invalid fields.
pub precedence_failure: ProtocolErrorCode,
}
/// Runs the complete end-to-end conformance example.
///
/// The provider resolves the current object from a Worldspace path for each
/// call. Interface observations remain separate from object projection, and all
/// successful calls carry independent object and interface validators.
///
/// # Errors
///
/// Returns an error if registration, observation, path resolution, dispatch, or
/// application-value decoding fails unexpectedly.
pub fn run() -> Result<DemoReport, Box<dyn Error>> {
let mut registry = InterfaceRegistry::new();
let catalog = registry.register(CatalogDefinition, Some(Validator::new(CATALOG_VALIDATOR)))?;
let audit = registry.register(AuditDefinition, None)?;
let diagnostics = registry.register(DiagnosticsDefinition, None)?;
let provider = ApplicationProvider {
catalog: catalog.clone(),
audit: audit.clone(),
};
let object = provider.fetch(OBJECT_PATH)?;
let catalog_response = registry
.fetch_interface(
object
.interfaces
.first()
.ok_or_else(|| io::Error::other("catalog interface was not published"))?,
)?
.protocol_response()?;
let audit_response = registry
.fetch_interface(
object
.interfaces
.get(1)
.ok_or_else(|| io::Error::other("audit interface was not published"))?,
)?
.protocol_response()?;
let published = dispatch_publish(
&provider,
catalog.reference(),
PublishRequest {
title: "Public APIs".into(),
body: Some("protocol values in, validated values out".into()),
source: wip::Entry::new("/drafts/public-apis")?,
visibility: Visibility::Public,
metadata: wip::JsonValue::Object(vec![wip::JsonMember {
name: "reviewed".into(),
value: wip::JsonValue::Boolean(true),
}]),
},
)?;
let rejected = dispatch_publish(
&provider,
catalog.reference(),
PublishRequest {
title: String::new(),
body: None,
source: wip::Entry::new("/drafts/untitled")?,
visibility: Visibility::Private,
metadata: wip::JsonValue::Null,
},
)?;
let catalog_status = dispatch_string(
&provider,
request(
OBJECT_PATH,
catalog.reference(),
Some(CATALOG_VALIDATOR),
"status",
BTreeMap::new(),
),
)?;
let audit_status = dispatch_string(
&provider,
request(
OBJECT_PATH,
audit.reference(),
None,
"status",
BTreeMap::new(),
),
)?;
let host_error = provider
.call_operation(request(
OBJECT_PATH,
catalog.reference(),
Some(CATALOG_VALIDATOR),
"backend_status",
BTreeMap::new(),
))
.expect_err("backend_status must model a host failure");
ensure_kind(&host_error, CallErrorKind::Internal)?;
let protocol_failure = host_error.protocol_error();
let unknown_protocol_failure = provider
.call_operation(request(
OBJECT_PATH,
catalog.reference(),
Some(CATALOG_VALIDATOR),
"uncertain_backend_status",
BTreeMap::new(),
))
.expect_err("uncertain_backend_status must preserve an unknown outcome")
.protocol_error();
let permission_failure = provider
.call_operation(request(
OBJECT_PATH,
catalog.reference(),
Some(CATALOG_VALIDATOR),
"restricted_status",
BTreeMap::new(),
))
.expect_err("restricted_status must be denied")
.protocol_error()
.code;
let validator_failure = provider
.call_operation(CallRequest {
target: Target {
path: OBJECT_PATH.into(),
validator: Some(b"stale-object".to_vec()),
},
interface: InterfaceTarget {
reference: diagnostics.reference().as_str().to_owned(),
validator: Some(b"stale-interface".to_vec()),
},
operation: "missing".into(),
arguments: BTreeMap::from([("unknown".into(), Value::Unit)]),
})
.expect_err("the stale object validator must fail first")
.protocol_error()
.code;
let interface_mismatch = provider
.call_operation(request(
OBJECT_PATH,
diagnostics.reference(),
None,
"diagnostics",
BTreeMap::new(),
))
.expect_err("registered but unexposed interface must not dispatch")
.protocol_error()
.code;
let interface_not_found = registry
.fetch_interface("missing-interface")
.expect_err("unknown interface references must not resolve")
.code;
let precedence_failure = provider
.call_operation(CallRequest {
target: Target {
path: "relative/path".into(),
validator: Some(b"stale-object".to_vec()),
},
interface: InterfaceTarget {
reference: diagnostics.reference().as_str().to_owned(),
validator: Some(b"stale-interface".to_vec()),
},
operation: "missing".into(),
arguments: BTreeMap::from([("unknown".into(), Value::Unit)]),
})
.expect_err("invalid path must have canonical precedence")
.protocol_error()
.code;
Ok(DemoReport {
object_name: object.name,
object_reference: object.r#ref,
object_validator: object.validator,
published_interfaces: object.interfaces,
catalog_interface_reference: catalog.reference().as_str().to_owned(),
audit_interface_reference: audit.reference().as_str().to_owned(),
catalog_descriptor_format: catalog_response.descriptor.format,
audit_descriptor_format: audit_response.descriptor.format,
published,
rejected,
catalog_status,
audit_status,
host_failure: host_error.kind(),
protocol_failure,
unknown_protocol_failure,
permission_failure,
validator_failure,
interface_mismatch,
interface_not_found,
precedence_failure,
})
}
fn ensure_kind(error: &wip_host::CallError, expected: CallErrorKind) -> Result<(), io::Error> {
if error.kind() == expected {
Ok(())
} else {
Err(io::Error::other(format!(
"unexpected host failure kind: {:?}",
error.kind()
)))
}
}
fn dispatch_publish(
provider: &ApplicationProvider,
catalog: &InterfaceRef,
request_value: PublishRequest,
) -> Result<PublishOutcome, Box<dyn Error>> {
let encoded_request = request_value.encode()?;
let result = provider.call_operation(request(
OBJECT_PATH,
catalog,
Some(CATALOG_VALIDATOR),
"publish",
BTreeMap::from([("request".into(), encoded_request)]),
))?;
Ok(PublishOutcome::decode(result.result)?)
}
fn dispatch_string(
provider: &ApplicationProvider,
request: CallRequest,
) -> Result<String, Box<dyn Error>> {
let result = provider.call_operation(request)?;
Ok(String::decode(result.result)?)
}
fn request(
path: &str,
interface: &InterfaceRef,
interface_validator: Option<&[u8]>,
operation: &str,
arguments: BTreeMap<String, Value>,
) -> CallRequest {
CallRequest {
target: Target {
path: path.into(),
validator: Some(OBJECT_VALIDATOR.to_vec()),
},
interface: InterfaceTarget {
reference: interface.as_str().to_owned(),
validator: interface_validator.map(<[u8]>::to_vec),
},
operation: operation.into(),
arguments,
}
}
struct ApplicationProvider {
catalog: RegisteredInterface<CatalogDefinition>,
audit: RegisteredInterface<AuditDefinition>,
}
impl ObjectProvider for ApplicationProvider {
type Object = ApplicationService;
fn with_object<R>(
&self,
_context: &ExecutionContext,
path: &str,
operation: impl FnOnce(&PublishedObject<Self::Object>) -> R,
) -> ProviderResult<R> {
if path != OBJECT_PATH {
return ProviderResult::NotFound;
}
let publication = PublishedObject::new(ApplicationService::new())
.expose(&self.catalog)
.expect("ApplicationService implements Catalog")
.expose(&self.audit)
.expect("ApplicationService implements Audit");
ProviderResult::Found(operation(&publication))
}
fn authorize(
&self,
_: &str,
_: &ApplicationService,
_: &InterfaceRef,
operation: &str,
) -> bool {
operation != "restricted_status"
}
}
struct ApplicationService {
object_validator: Validator,
backend_connection: String,
}
impl ApplicationService {
fn new() -> Self {
Self {
object_validator: Validator::new(OBJECT_VALIDATOR),
backend_connection: "private://article-database".into(),
}
}
}
impl WipObject for ApplicationService {
fn name(&self) -> &str {
"article-service"
}
fn description(&self) -> Option<&str> {
Some("Article publication service")
}
fn reference(&self) -> Option<&str> {
Some("article-service-instance")
}
fn validator(&self) -> Option<&Validator> {
Some(&self.object_validator)
}
fn requires_validator(&self, _: &InterfaceRef, _: &str) -> bool {
true
}
}
impl Catalog for ApplicationService {
fn publish(&self, request: PublishRequest) -> wip::OperationResult<PublishOutcome> {
if request.title.trim().is_empty() {
Ok(PublishOutcome::Rejected("a title is required".into()))
} else {
Ok(PublishOutcome::Published("article-1".into()))
}
}
fn status(&self) -> wip::OperationResult<String> {
Ok("catalog-ready".into())
}
fn backend_status(&self) -> wip::OperationResult<String> {
if self.backend_connection.starts_with("private://") {
Err(wip::HostError::internal(
"backend unavailable",
wip::EffectGuarantee::NotCommitted,
))
} else {
Ok("backend-ready".into())
}
}
fn uncertain_backend_status(&self) -> wip::OperationResult<String> {
Err(wip::HostError::internal(
"backend commit acknowledgement unavailable",
wip::EffectGuarantee::Unknown,
))
}
fn restricted_status(&self) -> wip::OperationResult<String> {
Ok("authorization hook should prevent this call".into())
}
}
impl Audit for ApplicationService {
fn status(&self) -> wip::OperationResult<String> {
Ok("audit-ready".into())
}
}
impl Diagnostics for ApplicationService {
fn diagnostics(&self) -> wip::OperationResult<String> {
Ok("host-private".into())
}
}
src/main.rs → crates/wip-public-api-example/src/main.rs
View File
crates/wip-public-api-example/tests/end_to_end.rs
+246
View File
@@ -0,0 +1,246 @@
use std::collections::BTreeMap;
use wip_host::CallErrorKind;
use wip_interface::{Entry, JsonMember, JsonValue, WipType};
use wip_protocol::{INTERFACE_FORMAT_V1, InterfaceDescriptor, Object, ProtocolErrorCode, Value};
use wip_public_api_example::{CatalogDefinition, PublishOutcome, PublishRequest, Visibility, run};
#[test]
fn public_crates_support_the_complete_qualified_end_to_end_scenario() {
let report = run().unwrap();
assert_eq!(report.object_name, "article-service");
assert_eq!(
report.object_reference.as_deref(),
Some("article-service-instance")
);
assert_eq!(
report.object_validator.as_deref(),
Some(b"object-v1".as_slice())
);
assert_eq!(
report.published_interfaces,
[
report.catalog_interface_reference.clone(),
report.audit_interface_reference.clone(),
],
"interfaces must retain explicit publication order"
);
assert_ne!(
report.catalog_interface_reference, report.audit_interface_reference,
"interfaces form an ordered set of distinct opaque references"
);
assert_eq!(report.catalog_descriptor_format, INTERFACE_FORMAT_V1);
assert_eq!(report.audit_descriptor_format, INTERFACE_FORMAT_V1);
assert_eq!(
report.published,
PublishOutcome::Published("article-1".into())
);
assert_eq!(
report.rejected,
PublishOutcome::Rejected("a title is required".into())
);
assert_eq!(report.catalog_status, "catalog-ready");
assert_eq!(report.audit_status, "audit-ready");
}
#[test]
fn domain_host_permission_and_validator_failures_remain_distinct() {
let report = run().unwrap();
assert!(matches!(report.rejected, PublishOutcome::Rejected(_)));
assert_eq!(report.host_failure, CallErrorKind::Internal);
assert_eq!(report.protocol_failure.code, ProtocolErrorCode::Internal);
assert_eq!(
report.unknown_protocol_failure.code,
ProtocolErrorCode::OperationOutcomeUnknown
);
assert_eq!(
report.permission_failure,
ProtocolErrorCode::PermissionDenied
);
assert_eq!(
report.validator_failure,
ProtocolErrorCode::ValidatorMismatch,
"validator recovery signals must not collapse to InvalidRequest"
);
}
#[test]
fn interface_mismatch_is_not_interface_not_found() {
let report = run().unwrap();
assert_eq!(
report.interface_mismatch,
ProtocolErrorCode::InterfaceMismatch
);
assert_eq!(
report.interface_not_found,
ProtocolErrorCode::InterfaceNotFound
);
assert_ne!(report.interface_mismatch, report.interface_not_found);
}
#[test]
fn invalid_path_keeps_canonical_failure_precedence() {
let report = run().unwrap();
assert_eq!(report.precedence_failure, ProtocolErrorCode::InvalidRequest);
assert_ne!(report.precedence_failure, report.validator_failure);
assert_ne!(report.precedence_failure, report.interface_mismatch);
}
#[test]
fn object_fields_keep_path_context_and_optional_ref_separate() {
// Listing every field makes this test fail to compile if a mandatory
// ObjectId is reintroduced into the canonical object DTO.
let object = Object {
name: "article".into(),
description: None,
interfaces: vec!["catalog-ref".into(), "audit-ref".into()],
r#ref: None,
validator: None,
};
object.validate_at_path("/library/article").unwrap();
assert_eq!(object.name, "article");
assert_eq!(object.r#ref, None);
assert_eq!(object.interfaces, ["catalog-ref", "audit-ref"]);
}
#[test]
fn interface_reference_is_observed_separately_from_descriptor_fields() {
// An exact destructuring pattern is compile-time coverage that the
// descriptor has no trait-name or opaque-reference `name` field.
let InterfaceDescriptor {
format,
documentation,
types,
operations,
} = CatalogDefinition::descriptor();
assert_eq!(format, INTERFACE_FORMAT_V1);
assert!(documentation.is_some());
assert!(!types.is_empty());
assert_eq!(
operations
.iter()
.map(|operation| operation.name.as_str())
.collect::<Vec<_>>(),
[
"publish",
"status",
"backend_status",
"uncertain_backend_status",
"restricted_status",
]
);
}
#[test]
fn application_record_enum_union_entry_and_json_use_schema_neutral_values() {
let request = PublishRequest {
title: "Canonical values".into(),
body: None,
source: Entry::new("/drafts/canonical-values").unwrap(),
visibility: Visibility::Public,
metadata: JsonValue::Object(vec![
JsonMember {
name: "tags".into(),
value: JsonValue::Array(vec![JsonValue::String("wip".into()), JsonValue::Null]),
},
JsonMember {
name: "ready".into(),
value: JsonValue::Boolean(true),
},
]),
};
let encoded = request.encode().unwrap();
assert_schema_neutral(&encoded);
let Value::Record(fields) = encoded else {
panic!("derived DTO record must use Value::Record")
};
assert_eq!(
fields.get("title"),
Some(&Value::String("Canonical values".into()))
);
assert!(!fields.contains_key("body"));
assert_eq!(
fields.get("source"),
Some(&Value::String("/drafts/canonical-values".into()))
);
assert_eq!(
fields.get("visibility"),
Some(&Value::String("Public".into()))
);
assert_eq!(
fields.get("metadata"),
Some(&Value::Record(BTreeMap::from([
("ready".into(), Value::Boolean(true)),
(
"tags".into(),
Value::List(vec![Value::String("wip".into()), Value::Unit])
),
])))
);
let outcome = PublishOutcome::Rejected("policy".into()).encode().unwrap();
assert_schema_neutral(&outcome);
assert_eq!(
outcome,
Value::Record(BTreeMap::from([
("$case".into(), Value::String("Rejected".into())),
("value".into(), Value::String("policy".into())),
]))
);
}
#[test]
fn entry_is_a_validated_canonical_absolute_path_string() {
let entry = Entry::new("/articles/one").unwrap();
assert_eq!(
entry.encode().unwrap(),
Value::String("/articles/one".into())
);
for invalid in [
"articles/one",
"/articles/",
"/articles//one",
"/articles/./one",
"/articles/../one",
] {
assert!(
Entry::new(invalid).is_err(),
"accepted invalid path {invalid}"
);
assert!(
Entry::decode(Value::String(invalid.into())).is_err(),
"decoded invalid path {invalid}"
);
}
}
fn assert_schema_neutral(value: &Value) {
// This exhaustive match is a compile-time regression guard: reintroducing
// semantic Entry/Enum/Union/Json variants makes the consumer non-exhaustive.
match value {
Value::Unit
| Value::Boolean(_)
| Value::Integer(_)
| Value::Number(_)
| Value::String(_)
| Value::Bytes(_) => {}
Value::Record(fields) => {
for value in fields.values() {
assert_schema_neutral(value);
}
}
Value::List(values) => {
for value in values {
assert_schema_neutral(value);
}
}
}
}
src/lib.rs
-627
View File
@@ -1,627 +0,0 @@
//! End-to-end use of the public WIP protocol, interface, and host APIs.
//!
//! This workspace package is deliberately separate from the three library
//! crates. It defines application DTOs and interfaces with `wip-interface`,
//! keeps its implementation private, publishes that implementation with
//! `wip-host`, and crosses the call boundary only with `wip-protocol` values.
//!
//! The complete scenario can be run as a normal binary or called directly:
//!
//! ```
//! let report = wip_public_api_example::run()?;
//!
//! assert_eq!(report.published_interfaces.len(), 2);
//! assert_eq!(report.catalog_status, "catalog-ready");
//! assert_eq!(report.audit_status, "audit-ready");
//! assert_eq!(
//! report.host_failure,
//! wip_host::CallErrorKind::Implementation,
//! );
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
#![deny(missing_docs)]
use std::error::Error;
use std::io;
use wip_host::{
CallErrorKind, CallRequest, InterfaceRef, InterfaceRegistry, InterfaceTarget, PublishedObject,
Validator, WipObject,
};
use wip_interface as wip;
use wip_interface::WipType;
use wip_protocol::{
InterfaceObservation, NamedValue, ObjectId, OperationOutcome, OperationResult, OperationTarget,
};
const OBJECT_ID: &str = "article-service";
const OBJECT_VALIDATOR: &[u8] = b"object-v1";
const CATALOG_VALIDATOR: &[u8] = b"catalog-v1";
/// An application-owned request DTO mapped to a protocol record.
#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
pub struct PublishRequest {
/// Title of the article to publish.
pub title: String,
/// Optional article body; omission is distinct from JSON null.
pub body: Option<String>,
}
/// The application domain result of a publication attempt.
///
/// Rejection is an ordinary typed result. It is intentionally distinct from a
/// host or backend failure, which uses [`wip::HostError`].
#[derive(Debug, Clone, PartialEq, Eq, wip::WipType)]
pub enum PublishOutcome {
/// Publication succeeded and returned its application identifier.
Published(String),
/// An application policy rejected the publication.
Rejected(String),
}
/// Article publication operations.
#[wip::interface]
pub trait Catalog {
/// Publishes an article or reports an application-domain rejection.
///
/// # Returns
/// The typed application outcome.
fn publish(
&self,
/// Application publication request.
request: PublishRequest,
) -> wip::OperationResult<PublishOutcome>;
/// Returns the catalog-qualified status.
///
/// # Returns
/// A catalog status label.
fn status(&self) -> wip::OperationResult<String>;
/// Demonstrates a host/backend failure rather than a domain result.
///
/// # Returns
/// A backend status only when the host can reach it.
fn backend_status(&self) -> wip::OperationResult<String>;
}
/// Audit operations exposed by the same object.
#[wip::interface]
pub trait Audit {
/// Returns the audit-qualified status.
///
/// This deliberately has the same operation name as [`Catalog::status`].
///
/// # Returns
/// An audit status label.
fn status(&self) -> wip::OperationResult<String>;
}
/// A registered but deliberately unexposed interface used to demonstrate that
/// Rust trait implementation does not imply protocol membership.
#[wip::interface]
pub trait Diagnostics {
/// Returns host-private diagnostics when the interface is explicitly exposed.
///
/// # Returns
/// A diagnostic label.
fn diagnostics(&self) -> wip::OperationResult<String>;
}
/// Observable outcomes from the complete public-API scenario.
#[derive(Debug, Clone, PartialEq)]
pub struct DemoReport {
/// Opaque interface references published by the object, in exposure order.
pub published_interfaces: Vec<String>,
/// Descriptor identity observed for the catalog interface.
pub catalog_descriptor: String,
/// Descriptor identity observed for the audit interface.
pub audit_descriptor: String,
/// Typed successful application result decoded from a validated `Value`.
pub published: PublishOutcome,
/// Typed application-domain rejection decoded from a validated `Value`.
pub rejected: PublishOutcome,
/// Result of the catalog-qualified `status` operation.
pub catalog_status: String,
/// Result of the audit-qualified `status` operation.
pub audit_status: String,
/// Stable failure kind produced by the deliberate host/backend failure.
pub host_failure: CallErrorKind,
/// A protocol-level operation result built from the host failure.
pub protocol_failure: OperationResult,
}
/// Runs the complete end-to-end example.
///
/// The function registers and observes generated descriptors, explicitly
/// exposes two interfaces on one host-private object, validates the resulting
/// protocol observation, dispatches interface-qualified calls using named
/// [`wip_protocol::Value`] arguments, decodes validated values back to
/// application types, and keeps a domain rejection distinct from a host
/// failure.
///
/// # Errors
///
/// Returns an error if registration, publication, observation validation,
/// dispatch, or application-value decoding fails unexpectedly.
pub fn run() -> Result<DemoReport, Box<dyn Error>> {
let mut registry = InterfaceRegistry::new();
let catalog = registry.register(CatalogDefinition, Some(Validator::new(CATALOG_VALIDATOR)))?;
let audit = registry.register(AuditDefinition, None)?;
let _diagnostics = registry.register(DiagnosticsDefinition, None)?;
let publication = PublishedObject::new(ApplicationService::new())
.expose(&catalog)?
.expose(&audit)?;
let object = publication.protocol_object();
// Model a transport/provider that retained only the protocol object's
// opaque strings, then resolved them back through the registry's public API.
let catalog_wire_reference = object
.interfaces
.first()
.ok_or_else(|| io::Error::other("catalog interface was not published"))?;
let audit_wire_reference = object
.interfaces
.get(1)
.ok_or_else(|| io::Error::other("audit interface was not published"))?;
let catalog_reference = registry
.resolve(catalog_wire_reference)
.ok_or_else(|| io::Error::other("published catalog reference did not resolve"))?;
let audit_reference = registry
.resolve(audit_wire_reference)
.ok_or_else(|| io::Error::other("published audit reference did not resolve"))?;
let catalog_observation = registry
.observe(&catalog_reference)
.ok_or_else(|| io::Error::other("registered catalog descriptor was not observable"))?;
let audit_observation = registry
.observe(&audit_reference)
.ok_or_else(|| io::Error::other("registered audit descriptor was not observable"))?;
InterfaceObservation {
object: object.clone(),
descriptors: vec![
catalog_observation.descriptor.clone(),
audit_observation.descriptor.clone(),
],
}
.validate()?;
let published = dispatch_publish(
&publication,
&catalog_observation.reference,
PublishRequest {
title: "Public APIs".into(),
body: Some("protocol values in, validated values out".into()),
},
)?;
let rejected = dispatch_publish(
&publication,
&catalog_observation.reference,
PublishRequest {
title: String::new(),
body: None,
},
)?;
let catalog_status = dispatch_string(
&publication,
request(
catalog_observation.reference.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"status",
vec![],
),
"catalog status",
)?;
let audit_status = dispatch_string(
&publication,
request(audit_observation.reference.clone(), None, "status", vec![]),
"audit status",
)?;
let host_error = match publication.dispatch(request(
catalog_observation.reference.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"backend_status",
vec![],
)) {
Ok(_) => {
return Err(io::Error::other(
"the deliberately unavailable example backend unexpectedly succeeded",
)
.into());
}
Err(error) => error,
};
if host_error.kind() != CallErrorKind::Implementation {
return Err(io::Error::other(format!(
"unexpected host failure kind: {:?}",
host_error.kind()
))
.into());
}
let protocol_error = host_error.protocol_error();
let protocol_failure = OperationResult {
target: OperationTarget {
object: ObjectId(OBJECT_ID.into()),
interface: catalog_observation.reference.as_str().into(),
operation: "backend_status".into(),
},
outcome: OperationOutcome::Failed(protocol_error),
};
Ok(DemoReport {
published_interfaces: object.interfaces,
catalog_descriptor: catalog_observation.descriptor.name,
audit_descriptor: audit_observation.descriptor.name,
published,
rejected,
catalog_status,
audit_status,
host_failure: host_error.kind(),
protocol_failure,
})
}
fn dispatch_publish(
publication: &PublishedObject<ApplicationService>,
catalog: &InterfaceRef,
request_value: PublishRequest,
) -> Result<PublishOutcome, Box<dyn Error>> {
let encoded_request = request_value.encode()?;
let result = publication.dispatch(request(
catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"publish",
vec![NamedValue {
name: "request".into(),
value: encoded_request,
}],
))?;
let value = result
.value
.ok_or_else(|| io::Error::other("publish returned no application value"))?;
Ok(PublishOutcome::decode(value)?)
}
fn dispatch_string(
publication: &PublishedObject<ApplicationService>,
request: CallRequest,
context: &str,
) -> Result<String, Box<dyn Error>> {
let result = publication.dispatch(request)?;
let value = result
.value
.ok_or_else(|| io::Error::other(format!("{context} returned no value")))?;
Ok(String::decode(value)?)
}
fn request(
interface: InterfaceRef,
interface_validator: Option<Validator>,
operation: &str,
arguments: Vec<NamedValue>,
) -> CallRequest {
CallRequest {
object: ObjectId(OBJECT_ID.into()),
object_validator: Some(Validator::new(OBJECT_VALIDATOR)),
interface: InterfaceTarget {
reference: interface,
validator: interface_validator,
},
operation: operation.into(),
arguments,
}
}
struct ApplicationService {
object_validator: Validator,
backend_connection: String,
}
impl ApplicationService {
fn new() -> Self {
Self {
object_validator: Validator::new(OBJECT_VALIDATOR),
backend_connection: "private://article-database".into(),
}
}
}
impl WipObject for ApplicationService {
fn id(&self) -> ObjectId {
ObjectId(OBJECT_ID.into())
}
fn validator(&self) -> Option<&Validator> {
Some(&self.object_validator)
}
fn requires_validator(&self) -> bool {
true
}
}
impl Catalog for ApplicationService {
fn publish(&self, request: PublishRequest) -> wip::OperationResult<PublishOutcome> {
if request.title.trim().is_empty() {
Ok(PublishOutcome::Rejected("a title is required".into()))
} else {
Ok(PublishOutcome::Published("article-1".into()))
}
}
fn status(&self) -> wip::OperationResult<String> {
Ok("catalog-ready".into())
}
fn backend_status(&self) -> wip::OperationResult<String> {
if self.backend_connection.starts_with("private://") {
Err(wip::HostError::new("backend unavailable"))
} else {
Ok("backend-ready".into())
}
}
}
impl Audit for ApplicationService {
fn status(&self) -> wip::OperationResult<String> {
Ok("audit-ready".into())
}
}
impl Diagnostics for ApplicationService {
fn diagnostics(&self) -> wip::OperationResult<String> {
Ok("host-private".into())
}
}
#[cfg(test)]
mod tests {
use super::*;
use wip_host::CallError;
use wip_interface::{CodecError, TypeDeclaration, TypeExpr};
use wip_protocol::{ProtocolErrorCategory, Value};
/// A deliberately inconsistent custom codec used to prove result validation.
pub struct InvalidValue;
impl WipType for InvalidValue {
fn type_expr() -> TypeExpr {
TypeExpr::String
}
fn collect_declarations(_: &mut Vec<TypeDeclaration>) {}
fn encode(self) -> Result<Value, CodecError> {
Ok(Value::Integer(7))
}
fn decode(_: Value) -> Result<Self, CodecError> {
Ok(Self)
}
}
/// Test-only interface whose custom codec emits an invalid result.
#[wip::interface]
pub trait BrokenResult {
/// Returns a value that violates its declared protocol type.
fn broken_result(&self) -> wip::OperationResult<InvalidValue>;
}
impl BrokenResult for ApplicationService {
fn broken_result(&self) -> wip::OperationResult<InvalidValue> {
Ok(InvalidValue)
}
}
struct Fixture {
publication: PublishedObject<ApplicationService>,
catalog: InterfaceRef,
audit: InterfaceRef,
diagnostics: InterfaceRef,
}
fn fixture() -> Fixture {
let mut registry = InterfaceRegistry::new();
let catalog = registry
.register(CatalogDefinition, Some(Validator::new(CATALOG_VALIDATOR)))
.unwrap();
let audit = registry.register(AuditDefinition, None).unwrap();
let diagnostics = registry.register(DiagnosticsDefinition, None).unwrap();
let publication = PublishedObject::new(ApplicationService::new())
.expose(&catalog)
.unwrap()
.expose(&audit)
.unwrap();
Fixture {
publication,
catalog: catalog.reference().clone(),
audit: audit.reference().clone(),
diagnostics: diagnostics.reference().clone(),
}
}
fn assert_failure(error: CallError, kind: CallErrorKind, category: ProtocolErrorCategory) {
assert_eq!(error.kind(), kind);
assert_eq!(error.protocol_error().category, category);
}
#[test]
fn interface_membership_and_same_name_operations_are_qualified() {
let fixture = fixture();
let catalog = dispatch_string(
&fixture.publication,
request(
fixture.catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"status",
vec![],
),
"catalog status",
)
.unwrap();
let audit = dispatch_string(
&fixture.publication,
request(fixture.audit.clone(), None, "status", vec![]),
"audit status",
)
.unwrap();
assert_eq!(catalog, "catalog-ready");
assert_eq!(audit, "audit-ready");
let not_exposed = fixture
.publication
.dispatch(request(fixture.diagnostics, None, "diagnostics", vec![]))
.unwrap_err();
assert_failure(
not_exposed,
CallErrorKind::InterfaceMismatch,
ProtocolErrorCategory::InterfaceNotFound,
);
}
#[test]
fn every_host_precondition_and_dispatch_failure_is_typed() {
let fixture = fixture();
let mut wrong_object = request(
fixture.catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"status",
vec![],
);
wrong_object.object = ObjectId("other-object".into());
assert_failure(
fixture.publication.dispatch(wrong_object).unwrap_err(),
CallErrorKind::ObjectNotFound,
ProtocolErrorCategory::ObjectNotFound,
);
let mut missing_object_validator = request(
fixture.catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"status",
vec![],
);
missing_object_validator.object_validator = None;
assert_failure(
fixture
.publication
.dispatch(missing_object_validator)
.unwrap_err(),
CallErrorKind::ValidatorRequired,
ProtocolErrorCategory::InvalidRequest,
);
let mut stale_object_validator = request(
fixture.catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"status",
vec![],
);
stale_object_validator.object_validator = Some(Validator::new(b"stale-object"));
assert_failure(
fixture
.publication
.dispatch(stale_object_validator)
.unwrap_err(),
CallErrorKind::ValidatorMismatch,
ProtocolErrorCategory::InvalidRequest,
);
assert_failure(
fixture
.publication
.dispatch(request(fixture.catalog.clone(), None, "status", vec![]))
.unwrap_err(),
CallErrorKind::InterfaceValidatorRequired,
ProtocolErrorCategory::InvalidRequest,
);
assert_failure(
fixture
.publication
.dispatch(request(
fixture.catalog.clone(),
Some(Validator::new(b"stale-interface")),
"status",
vec![],
))
.unwrap_err(),
CallErrorKind::InterfaceValidatorMismatch,
ProtocolErrorCategory::InvalidRequest,
);
assert_failure(
fixture
.publication
.dispatch(request(
fixture.catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"missing",
vec![],
))
.unwrap_err(),
CallErrorKind::OperationNotFound,
ProtocolErrorCategory::OperationNotFound,
);
assert_failure(
fixture
.publication
.dispatch(request(
fixture.catalog.clone(),
Some(Validator::new(CATALOG_VALIDATOR)),
"publish",
vec![NamedValue {
name: "request".into(),
value: Value::String("not a record".into()),
}],
))
.unwrap_err(),
CallErrorKind::InvalidArguments,
ProtocolErrorCategory::InvalidArguments,
);
assert_failure(
fixture
.publication
.dispatch(request(
fixture.catalog,
Some(Validator::new(CATALOG_VALIDATOR)),
"backend_status",
vec![],
))
.unwrap_err(),
CallErrorKind::Implementation,
ProtocolErrorCategory::Internal,
);
}
#[test]
fn invalid_implementation_result_never_crosses_the_host_boundary() {
let mut registry = InterfaceRegistry::new();
let broken = registry.register(BrokenResultDefinition, None).unwrap();
let publication = PublishedObject::new(ApplicationService::new())
.expose(&broken)
.unwrap();
let error = publication
.dispatch(request(
broken.reference().clone(),
None,
"broken_result",
vec![],
))
.unwrap_err();
assert_failure(
error,
CallErrorKind::InvalidResult,
ProtocolErrorCategory::Internal,
);
}
}
tests/end_to_end.rs
-27
View File
@@ -1,27 +0,0 @@
use wip_host::CallErrorKind;
use wip_protocol::{OperationOutcome, ProtocolErrorCategory};
use wip_public_api_example::{PublishOutcome, run};
#[test]
fn public_crates_support_the_complete_end_to_end_scenario() {
let report = run().unwrap();
assert_eq!(report.published_interfaces.len(), 2);
assert_eq!(report.catalog_descriptor, report.published_interfaces[0]);
assert_eq!(report.audit_descriptor, report.published_interfaces[1]);
assert_eq!(
report.published,
PublishOutcome::Published("article-1".into())
);
assert_eq!(
report.rejected,
PublishOutcome::Rejected("a title is required".into())
);
assert_eq!(report.catalog_status, "catalog-ready");
assert_eq!(report.audit_status, "audit-ready");
assert_eq!(report.host_failure, CallErrorKind::Implementation);
assert!(matches!(
report.protocol_failure.outcome,
OperationOutcome::Failed(error) if error.category == ProtocolErrorCategory::Internal
));
}