docs: document 0.1.0 crate release
This commit is contained in:
@@ -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.
|
||||
@@ -13,27 +13,34 @@ 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-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
|
||||
```
|
||||
@@ -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`
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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<dyn std::error::Error>> {
|
||||
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.
|
||||
@@ -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.
|
||||
@@ -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<Greeting>;
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user