Skip to content
Skills Library
Programming · Building & coding

ruststream-without-macros

/ruststream-without-macros

Use when a RustStream service is built without the `macros` feature, or when code must spell out what `#[subscriber]`, `#[ruststream::app]` and the derives generate: `Handle` impls, `subscriber(..).build()`, a hand-written `main`, manual `Outgoing`, `OutSlot`, `Deserialized` and `Serialized` impls.

Repository
ruststream ↗
Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when a RustStream service is built without the `macros` feature, or when code must spell out what `#[subscriber]`, `#[ruststream::app]` and the derives generate: `Handle` impls, `subscriber(..).build()`, a hand-written `main`, manual `Outgoing`, `OutSlot`, `Deserialized` and `Serialized` impls.

Original author description

Use when a RustStream service is built without the `macros` feature, or when code must spell out what `#[subscriber]`, `#[ruststream::app]` and the derives generate: `Handle` impls, `subscriber(..).build()`, a hand-written `main`, manual `Outgoing`, `OutSlot`, `Deserialized` and `Serialized` impls.

How it works

  1. A whole service
  2. Rules
  3. Common mistakes
Original SKILL.md headings · 158 lines, 755 words
SKILL.md preview
---
name: ruststream-without-macros
description: "Use when a RustStream service is built without the `macros` feature, or when code must spell out what `#[subscriber]`, `#[ruststream::app]` and the derives generate: `Handle` impls, `subscriber(..).build()`, a hand-written `main`, manual `Outgoing`, `OutSlot`, `Deserialized` and `Serialized` impls."
---

# RustStream without the macros

The attribute macros are sugar over public runtime API: a service without the `macros` feature
loses no capability, only the attribute surface. The handler body is a named type implementing
`Handle`, a registration is `subscriber(source, body)` plus settings and `.build()`, and `main`
is yours. This guidance targets ruststream 0.7. For everything the two styles share (outcomes,
the mount chain, publish policies, codecs, state) use the `ruststream` skill; for tests the
`ruststream-testing` skill.

Depth: [references/manual-path.md](references/manual-path.md) covers decoding, raw bytes,
state, headers, publishing, `Out` slots, middleware and what the chain reaches.

## A whole service

```rust
use std::convert::Infallible;
use std::error::Error;
use std::future::{Future, ready};

// Without `macros` the glob still brings the builder, `Handle`, `subscriber` and the traits the
// hand-written impls name.
use ruststream::memory::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize)]
struct Order {
    id: u64,
}

#[derive(Debug, Serialize)]
struct Confirmation {
    id: u64,
}

// What `#[derive(Outgoing)]` would write: no declared name, so `.to(..)` on the chain names it.
impl OutgoingDestination for Confirmation {
    type Form = CallerName;
}

impl MessageHeaders for Confirmation {
    type Contract = NoHeaders;
}

/// The handler body: the axes are the input, the reply, the injections, the context and the state.
struct Confirm;

impl Handle<Order, Confirmation> for Confirm {
    fn handle(
        &self,
        order: &Order,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<Confirmation, HandlerOutcome>> {
        tracing::info!(order.id, "confirming");
        ready(Ok(Confirmation { id: order.id }))
    }
}

/// Raw bytes are a named type that builds itself from the payload; `[u8]` is not an input.
struct Frame<'a>(&'a [u8]);

impl Deserialized for Frame<'_> {
    type Output<'a> = Frame<'a>;
    type Error = Infallible;

    fn from_payload(payload: &[u8]) -> Result<Frame<'_>, Self::Error> {
        Ok(Frame(payload))
    }
}

impl Input for Frame<'_> {
    type Axis = SoloDeserialized<Frame<'static>>;
}

struct Audit;

impl<'p> Handle<Frame<'p>> for Audit {
    fn handle(
        &self,
        frame: &Frame<'p>,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<(), HandlerOutcome>> {
        tracing::info!(len = frame.0.len(), "audit frame");
        ready(Ok(()))
    }
}

fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(MemoryBroker::new(), |b| {
        b.include(subscriber("orders", Confirm).reply().to("confirmations").build());
        b.include(subscriber("audit", Audit).build());
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    app().run().await?;
    Ok(())
}
```

## Rules

### The body is a named type; the signature decides the form

`Handle<In, R = (), O = (), C = (), S = ()>`: `In` is the input (`T` decoded, a `Deserialized`
type, `Message<H, T>` with typed headers, `[T]` for a batch), `R` the reply, `O` the `Out` slots
(`Outs<(E,)>`), `C` the broker context, `S` the application state read with `ctx.state()`. A
closure is not a body: what it would capture becomes a field of the type.

### The verdict is a `Result`, one spelling per shape

| Shape | Return |
|---|---|
| one message, no reply | `Result<(), HandlerOutcome>` (`Ok(())` acks) |
| one message, reply | `Result<Reply, HandlerOutcome>` |
| batch | `Result<(), Vec<HandlerOutcome>>` |
| batch with replies | `Result<Vec<Reply>, Vec<HandlerOutcome>>` |

Post-settle work rides the error side: `Err(HandlerOutcome::ack().and_after(fut))`.

### Register with `subscriber(..)` and seal with `.build()`

`b.include(subscriber("orders", Confirm).workers(nonzero!(4)).build())`. Settings, `.reply()`,
`.to(dest)`, `.describe(..)` and `.undocumented()` ride the chain before `.build()`; publish
policies (`.out_reply(..)`, `.out(Marker, ..)`) follow `include` exactly as on the macro path.
`Router::handle` and `BrokerScope::handle` are runtime machinery that skips the scope codec and the
settings; a service mounts through `include`.

### Keep anything that can panic inside the future

The dispatcher calls `handle(..)` and only then guards the returned future. A panic before the
future exists escapes the `on_failure(panic = ..)` policy and kills the task. A body that awaits
is written `async fn handle`; one with nothing to await returns `ready(..)`.

### `main` is yours

`#[tokio::main]` plus `app().run().await`. `run_until(future)` stops on a future you own;
`start()` returns a running handle for hosting beside another server. The attribute's command
line (`run`, `asyncapi gen`) is what the macro path adds.

## Common mistakes

| Symptom | Fix |
|---|---|
| `async fn on_order(order: Order) -> Confirmation` passed to a builder | a type implementing `Handle<Order, Confirmation>` |
| `app.subscriber("orders").handle(f)` | `b.include(subscriber("orders", Body).build())` inside `with_broker` |
| `RustStream::new(broker)` | `RustStream::new(AppInfo::new(name, version)).with_broker(broker, \|b\| { .. })` |
| raw bytes as `Bytes` or `&[u8]` | a `Deserialized` newtype plus its `Input` impl |
| `fn app() -> RustStream` with state or layers | `fn app() -> impl App`: state and layers change the type |
| a reply type with only `Serialize` | add `OutgoingDestination` and `MessageHeaders` impls |

The exact mapping from a handler shape to its axes is the macro expansion in
`crates/ruststream-macros/src/expand/unified.rs` of the core repository. Component pages show
every topic with a Manual tab: <https://powersemmi.github.io/ruststream/latest/components/>.
Files in this package (3)
  • SKILL.md 6 KB
  • agents/openai.yml 1 KB
  • references/manual-path.md 13 KB

Versions

The database has no other skills named ruststream-without-macros.

Database snapshot: 13.11.2026 · package version 01a7a14467bb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ruststream-core
    Use when changing the RustStream core repository itself (powersemmi/ruststream: `src/`, `crates/ruststream-macros`, `tests/`, `examples/`, the site), as a contributor: public items, errors, features, doctests, compile-fail snapshots, conformance suites, the local gates and the pull request.
  • 100ruststream
    Use when writing, changing or debugging a service built on the RustStream messaging framework (crates `ruststream` and `ruststream-*` broker crates such as nats, rdkafka, lapin, fred): subscriber handlers, the app, replies and publishing, acks, retries and dead letters, state,…
  • 100macros-code-review
    Reviews Rust macro code for hygiene issues, fragment misuse, compile-time impact, and procedural macro patterns. Use when reviewing macro_rules! definitions, procedural macros, derive macros, or attribute macros.
  • 100kit-webhooks
    Receive and verify Kit (formerly ConvertKit) webhooks. Use when setting up Kit webhook endpoints, debugging X-Kit-Signature verification, or handling email marketing events like subscriber.created, subscriber.activated, subscriber.unsubscribed, and subscriber.tag_added.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.