# alkhttp

HTTP interface for the alk stack: serves HTTP/1.1 + HTTP/2 on standard
ALPNs (with WebSocket upgrade carrying the channels protocol for browser
bidirectional access) and hosts the HTTP-backed call-protocol adapters.

alkhttp wraps [`alkcall`](https://crates.io/crates/alkcall) — the pure
call + channels protocol crate — and turns its operation registry into
an HTTP surface. It is the HTTP server host (a `ProtocolHandler` for the
IANA `h2`/`http/1.1` ALPNs) and the HTTP client host (the import
adapters that call out over `reqwest`) in one crate.

## What's inside

**Server side (`server` feature)** — the producer-facing HTTP surface:

- `HttpAdapter` — an axum `Router` driven by hyper's HTTP/1.1 and HTTP/2
  connection handling over a `BiStream`, served on standard ALPNs so any
  HTTP client connects without knowing about the alk stack.
- Six fixed gateway endpoints — the sole HTTP invoke path (no
  per-operation REST tree):
  `GET /search`, `GET /schema?name=…`, `POST /call`, `POST /batch`,
  `POST /subscribe` (SSE), `POST /publish` (NDJSON).
- `/healthz`, `/openapi.json` (a `to_openapi` projection of the local
  registry), and `/mcp` (the MCP tool gateway, feature `mcp`).
- WebSocket upgrade on `/alk/channels` carrying the channels protocol:
  8-byte chunk multiplexing with channel 0 pre-negotiated as `alk/call`,
  so a browser runs the native bidirectional call-protocol session.
- Bearer auth, a stealth decoy surface for unknown paths, custom-route
  mounting, and assembly hooks for WS session caps and timeouts.

**Client side (`client` feature)** — the consumer-facing import
adapters, each producing ordinary `HandlerRegistration` bundles for an
`alkcall` registry:

- `from_openapi` — import an external HTTP API described by an OpenAPI
  document (JSON or YAML), forwarding calls over the shared reqwest
  client.
- `from_jsonschema` — import one non-OpenAPI HTTP endpoint behind a
  caller-built `OperationSpec`.
- `from_mcp` — import a remote MCP server's tools as operations over
  streamable HTTP (feature `mcp`).
- `from_wss` — import a remote alk node's operations over a WSS
  channels connection (feature `wss`).
- `SharedHttpClient` — the hot-reloadable reqwest stack all `from_*`
  forwarding rides: same-host-only redirects, idempotent-only retries
  with a wall-clock budget, `Retry-After` support, TLS config, and
  streaming byte caps.

**Both sides (`openapi` feature, implied)** — the shared OpenAPI
document model plus the reverse projections `to_openapi` (generate the
gateway's OpenAPI document from the registry) and `to_mcp` (expose local
operations as MCP tools).

## Quick start

### Serve the gateway over HTTP

`HttpAdapter` implements alkcall's `ProtocolHandler`; the endpoint /
accept loop is the consumer's concern (dial and TLS live downstream).
Wire it for the ALPN you serve and drive it with your connection source:

```rust
use std::sync::Arc;

use alkcall::core::auth::IdentityProvider;
use alkcall::core::types::Connection;
use alkcall::registry::registration::OperationRegistry;
use alkhttp::server::{DecoyConfig, HttpAdapter};

let registry = Arc::new(OperationRegistry::new());
let provider: Arc<dyn IdentityProvider> = /* your identity provider */;

let adapter = HttpAdapter::h2(provider, registry)
    .with_decoy(DecoyConfig::NotFound);

// adapter.alpn() == b"h2" — register it in your handler registry for
// that ALPN; each accepted Connection is handled by
// ProtocolHandler::handle(&adapter, connection, &auth).
```

Once wired, HTTP callers get the fixed gateway surface. Discovery is
per-caller, filtered by `AccessControl`:

```text
GET  /search                      → { "request_id": …, "result": "ok",
                                      "output": { "operations": [ … ] } }
GET  /schema?name=fs/readFile     → the operation's input/output schema
POST /call                        ← { "operation": "fs/readFile",
                                      "input": { … } }
POST /batch                       ← [ { "operation": …, "input": … }, … ]
POST /subscribe                   → SSE stream of call-protocol envelopes
POST /publish                     ← NDJSON body of published chunks
```

`/openapi.json` serves the same surface as an OpenAPI document, so
standard tooling can drive the gateway without knowing the alk stack.

### Import an OpenAPI-described API

```rust
use std::collections::HashMap;
use std::sync::Arc;

use alkhttp::adapters::{FromOpenAPI, HttpServiceConfig, OpenAPISpec};
use alkhttp::client::{HttpClientConfig, SharedHttpClient};

let doc = r#"{"openapi":"3.0.0","info":{"title":"Widgets","version":"1"},
    "paths":{"/widgets":{"get":{"operationId":"listWidgets",
    "responses":{"200":{"content":{"application/json":{"schema":{}}}}}}}}}"#;

let spec = OpenAPISpec::from_json(doc)?;
let config = HttpServiceConfig {
    namespace: "widgets".to_string(),
    base_url: "https://widgets.example.com".to_string(),
    auth: None, // or Some(HttpAuthScheme::Bearer) — the credential is
                // injected per-call from Capabilities, never from config
    default_headers: HashMap::new(),
};
let http_client = Arc::new(SharedHttpClient::new(HttpClientConfig::default())?);

let adapter = FromOpenAPI::new(spec, config, http_client);
let registrations = alkcall::client::OperationAdapter::import(&adapter).await?;

let mut registry = alkcall::registry::registration::OperationRegistry::new();
for reg in registrations {
    registry.register(reg)?;
}
// "widgets/listWidgets" is now callable — and composable — through the
// call protocol and the gateway.
```

Imported operations register `Visibility::Internal` (they are
composition material); an External facade op composed over them via
`ctx.env.invoke` is what the wire sees.

### WebSocket for browsers

A browser upgrades `GET /alk/channels` (Bearer token in the
`Authorization` header) to a WebSocket and speaks the channels protocol
in binary messages: an 8-byte chunk header multiplexes N channels;
channel 0 is pre-negotiated as `alk/call` and runs the native
call-protocol session. Both sides can initiate calls; the browser can
also register operations and open channels — it is a full consumer and
producer on its own connection-local overlay.

## Feature flags

The crate is feature-sided — build one side, or both:

| Feature | Default | Gates |
|---------|---------|-------|
| `server` | yes | the axum host, gateway routes, WS upgrade, `/healthz`, `/openapi.json`, `to_openapi` |
| `client` | yes | the shared outbound client host, `from_openapi`, `from_jsonschema` |
| `openapi` | (implied) | the shared OpenAPI document model (implied by both sides) |
| `mcp` | no | `from_mcp` (needs `client`) and `to_mcp` (needs `server`) |
| `wss` | no | the `from_wss` consumer adapter |
| `h2`, `http1` | yes | the server's HTTP protocol features (imply `server`) |

A lean single-side build takes `default-features = false` plus the side
it needs:

```toml
alkhttp = { version = "0.5.0", default-features = false, features = ["server"] }
```

## Security posture

- **No secret material on the wire.** Request/response payloads and
  headers carry no keys or tokens beyond the caller's own Bearer
  credential. Outbound credentials flow vault → assembly layer →
  `Capabilities` → handler; the `from_*` adapters are the injection
  point, and no handler reads `std::env::var`.
- **Stealth mode.** The HTTP surface serves on standard ALPNs, and
  unregistered paths answer with a configurable decoy (fake nginx 404,
  static site, or redirect) instead of advertising the gateway.
- **Tight forwarding defaults.** Same-host-only redirects,
  idempotent-only retries with a wall-clock budget and `Retry-After`
  ceiling, 30 s request / 10 s connect / 30 s read timeouts, a 2 MiB
  gateway body cap (8 MiB on `/mcp`), and a 1 GiB streamed-bytes cap per
  subscription.
- **Internal-by-default imports.** Adapter-registered operations are
  invisible to direct wire calls (`NOT_FOUND`) until composed behind an
  External facade.

## Documentation

- [Architecture docs](docs/architecture/README.md) — the authoritative
  spec: ADRs 001–071, component documents, and open questions.
- [API docs](https://docs.rs/alkhttp) — full crate documentation on
  docs.rs.
- [Changelog](CHANGELOG.md)

## License

MIT OR Apache-2.0 — see [LICENSE-MIT](LICENSE-MIT) and
[LICENSE-APACHE](LICENSE-APACHE).