120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
---
|
|
id: core/crate-init
|
|
name: Initialize alknet-core crate with Cargo.toml, dependencies, and module skeleton
|
|
status: completed
|
|
depends_on: []
|
|
scope: moderate
|
|
risk: low
|
|
impact: project
|
|
level: implementation
|
|
---
|
|
|
|
## Description
|
|
|
|
Initialize the `alknet-core` crate from scratch. The workspace currently has
|
|
only `alknet-vault`. This task creates the crate directory, `Cargo.toml`,
|
|
`lib.rs`, and the module skeleton that subsequent core tasks will fill in.
|
|
|
|
### Crate setup
|
|
|
|
Create `crates/alknet-core/` with:
|
|
|
|
- `Cargo.toml` — package metadata, dependencies, feature flags
|
|
- `src/lib.rs` — crate root with module declarations and re-exports
|
|
- Module skeleton files (empty or with `// TODO` markers) for:
|
|
- `src/types.rs` — ProtocolHandler, HandlerError, Connection, BiStream, SendStream, RecvStream, StreamError, Capabilities
|
|
- `src/auth.rs` — AuthContext, Identity, IdentityProvider, AuthToken, ConfigIdentityProvider
|
|
- `src/config.rs` — StaticConfig, DynamicConfig, AuthPolicy, ApiKeyEntry, RateLimitConfig, ConfigReloadHandle, ConfigError, TlsIdentity
|
|
- `src/endpoint.rs` — AlknetEndpoint, HandlerRegistry, EndpointError
|
|
|
|
### Dependencies
|
|
|
|
Per the architecture specs (overview.md, core/README.md, endpoint.md):
|
|
|
|
| Crate | Purpose |
|
|
|-------|---------|
|
|
| `tokio` 1 (full) | Async runtime, watch channel for shutdown |
|
|
| `quinn` | QUIC endpoint (feature-gated) |
|
|
| `iroh` | P2P relay-assisted endpoint (feature-gated) |
|
|
| `rustls` | TLS implementation |
|
|
| `rustls-pki-types` | TLS types (CertificateDer, PrivateKeyDer) |
|
|
| `serde` 1 | Serialization for config types |
|
|
| `serde_json` 1 | JSON for config, JSON Schema values |
|
|
| `toml` 0.8 | Config file format |
|
|
| `arc-swap` 1 | Atomic config swap for DynamicConfig |
|
|
| `async-trait` 0.1 | ProtocolHandler trait (async fn in trait) |
|
|
| `tracing` 0.1 | Structured logging |
|
|
| `thiserror` 2 | Error enums |
|
|
| `zeroize` 1 | Capabilities zeroization |
|
|
| `bytes` 1 | Byte buffer types for streams |
|
|
| `futures` | AsyncRead/AsyncWrite for BiStream trait |
|
|
|
|
### Feature flags
|
|
|
|
```toml
|
|
[features]
|
|
default = ["quinn"]
|
|
quinn = ["dep:quinn"]
|
|
iroh = ["dep:iroh"]
|
|
```
|
|
|
|
Both quinn and iroh are optional, both can be active simultaneously (ADR-010).
|
|
`quinn` is default-on for the common case; `iroh` is opt-in.
|
|
|
|
### Workspace Cargo.toml
|
|
|
|
Add `crates/alknet-core` to the workspace `members` list in the root
|
|
`Cargo.toml`.
|
|
|
|
### Module skeleton
|
|
|
|
```rust
|
|
// src/lib.rs
|
|
//! alknet-core: Core library for ALPN-based protocol dispatch.
|
|
|
|
pub mod types;
|
|
pub mod auth;
|
|
pub mod config;
|
|
pub mod endpoint;
|
|
|
|
// Re-exports (filled in by subsequent tasks)
|
|
```
|
|
|
|
Each module file gets a doc comment and `// TODO: implement` marker. The
|
|
subsequent tasks (core-types, config, auth, endpoint) fill these in.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `crates/alknet-core/Cargo.toml` exists with all dependencies and feature flags
|
|
- [ ] `crates/alknet-core/src/lib.rs` exists with module declarations
|
|
- [ ] Module skeleton files exist: `types.rs`, `auth.rs`, `config.rs`, `endpoint.rs`
|
|
- [ ] Root `Cargo.toml` `members` list includes `crates/alknet-core`
|
|
- [ ] `cargo check -p alknet-core` succeeds
|
|
- [ ] `cargo clippy -p alknet-core` succeeds with no warnings
|
|
- [ ] Dual licensing: `MIT OR Apache-2.0` (workspace-inherited)
|
|
|
|
## References
|
|
|
|
- docs/architecture/overview.md — crate graph, shared types
|
|
- docs/architecture/crates/core/README.md — crate index
|
|
- docs/architecture/crates/core/core-types.md — types to implement
|
|
- docs/architecture/crates/core/endpoint.md — endpoint, features (quinn + iroh)
|
|
- docs/architecture/crates/core/config.md — config types
|
|
- docs/architecture/crates/core/auth.md — auth types
|
|
- docs/architecture/decisions/003-crate-decomposition.md — ADR-003
|
|
- docs/architecture/decisions/010-alpn-router-and-endpoint.md — ADR-010 (feature-gating)
|
|
|
|
## Notes
|
|
|
|
> This is the foundational setup task for alknet-core. All subsequent core
|
|
> tasks depend on this one. The crate has no alknet dependencies (vault is
|
|
> standalone; core doesn't depend on vault). The feature flags for quinn/iroh
|
|
> are important — both are optional and can be active simultaneously.
|
|
|
|
## Summary
|
|
|
|
Created `crates/alknet-core/` with `Cargo.toml` (all 14 dependencies, quinn/iroh
|
|
feature flags per ADR-010), `src/lib.rs` with module declarations, and 4 skeleton
|
|
module files (`types.rs`, `auth.rs`, `config.rs`, `endpoint.rs`) with doc comments
|
|
and TODO markers. Added to workspace `members`. `cargo check`/`clippy`/`fmt` clean.
|
|
Merged to develop. |