diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8572a10 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,16 @@ +# Changelog + +All notable changes to the published WIP Rust crates are documented here. + +## 0.1.0 + +Initial public release of: + +- `wip-protocol`: transport-independent WIP logical model and validation. +- `wip-interface-macros`: procedural-macro implementation for interface and DTO declarations. +- `wip-interface`: public Rust interface-authoring facade and typed value codecs. +- `wip-host`: request-scoped publication, precondition validation, and qualified operation dispatch. +- `wip-http`: framework-independent WIP over HTTP v1 routes, strict JSON codecs, and failure classification. +- `wip-client`: stateful Known Space, interest-driven acquisition, request ownership, and operation lifecycle. + +The repository also contains non-published filesystem server, terminal client, and public-API conformance packages. diff --git a/README.md b/README.md index 815f4f5..f22b41d 100644 --- a/README.md +++ b/README.md @@ -13,29 +13,36 @@ repository root is not itself a package. ## Crate graph and responsibilities ```text -wip-tui (interactive Worldspace explorer and operation editor) -├── wip-client Known Space, request identity, validators, and calls -├── wip-http framework-neutral HTTP request/response messages -└── wip-protocol descriptors and logical values +Published libraries -wip-fs-server (request-time filesystem projection and loopback listener) -├── wip-http standard routes/codecs/envelopes -├── wip-host request-scoped publication and dispatch -└── wip-interface macro-generated filesystem capabilities +wip-client +├── wip-http +│ └── wip-protocol +└── wip-protocol -wip-public-api-example (workspace-only executable, integration tests, doctest) -├── wip-protocol logical declarations, values, calls, and validation -├── wip-http standard HTTP v1 routes, JSON codecs, and envelopes +wip-host +├── wip-interface +│ ├── wip-interface-macros │ └── wip-protocol -├── wip-client stateful Known Space, lazy tree, observation, and call runtime -│ ├── wip-http -│ └── wip-protocol -├── wip-interface application DTO codecs and interface authoring facade -│ ├── wip-protocol -│ └── wip-interface-macros proc-macro implementation detail -└── wip-host descriptor registry, publication, and qualified dispatch - ├── wip-interface - └── wip-protocol +└── wip-protocol + +Workspace-only applications and conformance consumers + +wip-tui +├── wip-client +├── wip-http +└── wip-protocol + +wip-fs-server +├── wip-host +├── wip-http +├── wip-interface +└── wip-protocol + +wip-public-api-example +├── wip-host +├── wip-interface +└── wip-protocol ``` | Crate | Responsibility | Does not own | @@ -50,6 +57,21 @@ wip-public-api-example (workspace-only executable, integration tests, doctest) | `wip-fs-server` | Linux directory-handle-confined request-time projection, complete depth-bounded observations and bounded file operations, standard `wip-http` dispatch, and a loopback HTTP binary. | A new wire profile, implicit symlink following, non-loopback cleartext, authentication policy, TLS termination, 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. | +## Published crates + +The `0.1.0` release consists of these six crates: + +- `wip-protocol` +- `wip-interface-macros` — implementation dependency re-exported by `wip-interface` +- `wip-interface` +- `wip-host` +- `wip-http` +- `wip-client` + +The filesystem server, terminal client, and public-API example are workspace-only packages and set `publish = false`. All workspace packages require Rust 1.88 or newer and are licensed under either Apache-2.0 or MIT at your option. + +See [RELEASING.md](RELEASING.md) for the dependency-ordered crates.io procedure and [CHANGELOG.md](CHANGELOG.md) for release contents. + 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 `wip-http` diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..e9707b6 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,75 @@ +# Releasing + +The six crates published from this workspace use one version and must be released in dependency order. The filesystem server, terminal client, and public-API example set `publish = false` and are never uploaded. + +## Preconditions + +1. Work from a clean `master` whose `HEAD` matches `origin/master`. +2. Confirm the intended version in `[workspace.package]` and every internal requirement in `[workspace.dependencies]`. +3. Confirm ownership of all six names on crates.io. +4. Run the complete repository validation suite: + +```console +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 +``` + +## Publish order + +Before uploading anything, dry-run the exact public package set together. Cargo uses a temporary local registry for unpublished workspace dependencies during this check: + +```console +cargo publish --dry-run --workspace \ + --exclude wip-fs-server \ + --exclude wip-public-api-example \ + --exclude wip-tui +``` + +Then dry-run and publish each layer before moving to a crate that depends on it: + +```console +cargo publish --dry-run --package wip-protocol +cargo publish --package wip-protocol + +cargo publish --dry-run --package wip-interface-macros +cargo publish --package wip-interface-macros +``` + +Wait until both versions are available from the crates.io index, then continue: + +```console +cargo publish --dry-run --package wip-interface +cargo publish --package wip-interface + +cargo publish --dry-run --package wip-http +cargo publish --package wip-http +``` + +After those versions are available from the index: + +```console +cargo publish --dry-run --package wip-host +cargo publish --package wip-host + +cargo publish --dry-run --package wip-client +cargo publish --package wip-client +``` + +Registry propagation can take time. A dependent dry-run reporting that a WIP crate is unavailable means the previous publish is not visible in the selected registry yet; do not bypass verification. + +## Tag + +After all six uploads resolve successfully, tag the exact published commit and push the tag: + +```console +git tag -a v0.1.0 -m "release: 0.1.0" +git push origin v0.1.0 +``` + +Do not move or recreate a published version or its tag. Prepare a new version for any subsequent correction. diff --git a/crates/wip-client/README.md b/crates/wip-client/README.md new file mode 100644 index 0000000..77b6dda --- /dev/null +++ b/crates/wip-client/README.md @@ -0,0 +1,16 @@ +# wip-client + +Presentation-independent stateful runtime for Web Interface Protocol (WIP) clients. + +`wip-client` manages endpoint- and security-context-isolated Known Space, object and Interface Descriptor observations, bounded request ownership, supersession, out-of-order response suppression, validator recovery, and operation call contexts. It produces and consumes framework-neutral `wip-http` messages but performs no network I/O and contains no UI types. + +```toml +[dependencies] +wip-client = "0.1.0" +``` + +Applications provide the HTTP adapter and presentation layer, send each prepared request exactly as owned by the runtime, then return the corresponding response for completion. + +See the [API documentation](https://docs.rs/wip-client) for session, acquisition, cache, and call APIs. + +Licensed under either of Apache-2.0 or MIT at your option. diff --git a/crates/wip-host/README.md b/crates/wip-host/README.md new file mode 100644 index 0000000..b786252 --- /dev/null +++ b/crates/wip-host/README.md @@ -0,0 +1,15 @@ +# wip-host + +Framework-independent Host publication and operation dispatch for the Web Interface Protocol (WIP). + +`wip-host` registers generated interfaces, explicitly publishes them on request-scoped objects, validates object and interface preconditions, and performs interface-qualified operation dispatch against one host-owned instance. Backend transactions, persistence, and network serving remain application responsibilities. + +```toml +[dependencies] +wip-host = "0.1.0" +wip-interface = "0.1.0" +``` + +See the [API documentation](https://docs.rs/wip-host) for publication, provider, execution-context, and effect-guarantee boundaries. + +Licensed under either of Apache-2.0 or MIT at your option. diff --git a/crates/wip-http/README.md b/crates/wip-http/README.md new file mode 100644 index 0000000..ac266a8 --- /dev/null +++ b/crates/wip-http/README.md @@ -0,0 +1,31 @@ +# wip-http + +Framework-independent WIP over HTTP v1 endpoint, route, JSON codec, and response-classification support. + +The crate maps the three WIP Core interactions to fixed HTTP routes and strict UTF-8 JSON representations. It constructs and validates `http` request and response values but deliberately performs no network I/O and does not define TLS, authentication, proxy, or connection policy. + +```toml +[dependencies] +wip-http = "0.1.0" +``` + +```rust +use wip_http::wip_protocol::ObserveRequest; +use wip_http::{Endpoint, Limits, encode_observe_request}; + +fn main() -> Result<(), Box> { + let endpoint = Endpoint::parse("https://example.test/wip")?; + let limits = Limits::new(64 * 1024, 1024 * 1024, 64)?; + let request = encode_observe_request( + &endpoint, + &ObserveRequest { path: "/".into(), depth: 0 }, + limits, + )?; + assert_eq!(request.uri(), "https://example.test/wip/v1/observe"); + Ok(()) +} +``` + +See the [API documentation](https://docs.rs/wip-http) for codec and failure-boundary details. + +Licensed under either of Apache-2.0 or MIT at your option. diff --git a/crates/wip-interface-macros/README.md b/crates/wip-interface-macros/README.md new file mode 100644 index 0000000..be41d0a --- /dev/null +++ b/crates/wip-interface-macros/README.md @@ -0,0 +1,9 @@ +# wip-interface-macros + +Procedural-macro implementation used by [`wip-interface`](https://crates.io/crates/wip-interface). + +Applications should depend on `wip-interface`, which re-exports `#[interface]` and `#[derive(WipType)]` together with the traits and types required by generated code. Direct use of this implementation crate is not a supported application API. + +See the [API documentation](https://docs.rs/wip-interface-macros) for the exported macro entry points. + +Licensed under either of Apache-2.0 or MIT at your option. diff --git a/crates/wip-interface/README.md b/crates/wip-interface/README.md new file mode 100644 index 0000000..ab7eda1 --- /dev/null +++ b/crates/wip-interface/README.md @@ -0,0 +1,32 @@ +# wip-interface + +Public Rust authoring API for Web Interface Protocol (WIP) interfaces and application DTO codecs. + +The crate re-exports `#[interface]` and `#[derive(WipType)]`, generates Interface Descriptors and typed dispatch companions, and converts application-owned Rust values to and from the transport-independent value model. + +```toml +[dependencies] +wip-interface = "0.1.0" +``` + +```rust +use wip_interface as wip; + +#[derive(wip::WipType)] +struct Greeting { + message: String, +} + +#[wip::interface] +pub trait Greeter { + /// Builds a greeting. + /// + /// # Returns + /// The generated greeting. + fn greet(&self, name: String) -> wip::OperationResult; +} +``` + +See the [API documentation](https://docs.rs/wip-interface) for supported interface syntax, DTO shapes, and failure semantics. + +Licensed under either of Apache-2.0 or MIT at your option. diff --git a/crates/wip-protocol/README.md b/crates/wip-protocol/README.md new file mode 100644 index 0000000..8f23418 --- /dev/null +++ b/crates/wip-protocol/README.md @@ -0,0 +1,14 @@ +# wip-protocol + +Transport-independent logical types and validation for the Web Interface Protocol (WIP). + +This crate defines the canonical Object and Interface Descriptor models, the three Core interaction request and response types, schema-neutral operation `Value`s, validators, protocol errors, and structural validation. It does not define an HTTP mapping, application DTOs, persistence, or network I/O. + +```toml +[dependencies] +wip-protocol = "0.1.0" +``` + +See the [API documentation](https://docs.rs/wip-protocol) for the complete model and validation rules. + +Licensed under either of Apache-2.0 or MIT at your option.