photon_macros/
lib.rs

1//! Proc macros for Photon pub/sub.
2//!
3//! ## Entry points
4//!
5//! - [`topic`] — typed publish/subscribe on a struct; submits a topic descriptor to inventory
6//! - [`subscribe`] — registers a handler; requires [`Photon::start_executor`](https://docs.rs/uf-photon/latest/photon/struct.Photon.html#method.start_executor) at boot
7//!
8//! Attribute tables: [`photon::config`](https://docs.rs/uf-photon/latest/photon/config/).
9//! Getting started: [declare topics](https://docs.rs/uf-photon/latest/photon/#3-declare-topics-and-handlers).
10
11use proc_macro::TokenStream;
12
13mod subscribe;
14mod topic;
15
16/// Marks a struct as a Photon topic, generating typed publish/subscribe APIs.
17///
18/// Registers a topic descriptor in Quark inventory. With
19/// [`PhotonBuilder::auto_registry`](https://docs.rs/uf-photon/latest/photon/struct.PhotonBuilder.html#method.auto_registry),
20/// the host discovers it at boot. Prefer `EventType { … }.publish_on(&photon)` with an explicit
21/// [`Photon`](https://docs.rs/uf-photon/latest/photon/struct.Photon.html) handle.
22///
23/// | Attribute | Purpose |
24/// |-----------|---------|
25/// | `name = "…"` | Topic stream name (required) |
26/// | `keyed_by = "field"` | Partition key field on the struct |
27/// | `shards = N` | Virtual shard count for consumer groups |
28///
29/// Full attribute reference: [`photon::config`](https://docs.rs/uf-photon/latest/photon/config/#photon-topic).
30/// Getting started: [Mode 1](https://docs.rs/uf-photon/latest/photon/#mode-1--embedded-one-binary).
31///
32/// # Usage
33///
34/// ```ignore
35/// use futures::StreamExt;
36/// use photon::{topic, Photon, SubscribeOpts};
37///
38/// #[topic(name = "user.notifications", keyed_by = "user_id")]
39/// pub struct NotificationPushed {
40///     pub user_id: String,
41/// }
42///
43/// # async fn demo(photon: &Photon) -> photon::Result<()> {
44/// NotificationPushed { user_id: "u1".into() }
45///     .publish_on(photon)
46///     .await?;
47///
48/// let mut stream = NotificationPushed::subscribe_on(
49///     photon,
50///     SubscribeOpts::default_ephemeral(),
51/// )
52/// .await?;
53/// if let Some(Ok(envelope)) = stream.next().await {
54///     let _ = envelope.payload.user_id;
55/// }
56/// # Ok(())
57/// # }
58/// ```
59#[proc_macro_attribute]
60pub fn topic(attr: TokenStream, item: TokenStream) -> TokenStream {
61    topic::topic_impl(attr, item)
62}
63
64/// Marks a function as a subscription handler registered via inventory.
65///
66/// The host must call
67/// [`Photon::start_executor`](https://docs.rs/uf-photon/latest/photon/struct.Photon.html#method.start_executor)
68/// (Mode 1 hosts and Mode 2 **workers**) so inventory-registered handlers run. Publishers that
69/// only emit events can omit the executor.
70///
71/// | Attribute | Purpose |
72/// |-----------|---------|
73/// | `topic = "…"` | Topic name to consume (required) |
74/// | `durable = "name"` | Checkpointed subscription name |
75/// | `group = "id"` | Consumer-group load balancing |
76///
77/// Full attribute reference: [`photon::config`](https://docs.rs/uf-photon/latest/photon/config/#photon-subscribe).
78/// Getting started: [Mode 2 worker](https://docs.rs/uf-photon/latest/photon/#worker-binary).
79///
80/// # Usage (v1 — `Box<dyn Actor>`)
81///
82/// ```ignore
83/// use photon::{topic, subscribe, Actor, Result};
84///
85/// #[topic(name = "user.notifications")]
86/// pub struct NotificationPushed {
87///     pub user_id: String,
88/// }
89///
90/// #[subscribe(topic = "user.notifications", durable = "push-worker")]
91/// async fn on_notification(
92///     _actor: Box<dyn Actor>,
93///     _event: NotificationPushed,
94/// ) -> Result<()> {
95///     Ok(())
96/// }
97/// ```
98///
99/// # Actor bindings (v2)
100///
101/// The first parameter must be a simple identifier typed as one of:
102///
103/// - `Box<dyn Actor>` — reconstruct as-is (v1)
104/// - `Arc<dyn Actor>` — `Arc::from(reconstruct()?)`
105/// - `Box<Concrete>` / `Arc<Concrete>` — downcast via `Actor::into_any`; failure maps to
106///   `PhotonError::Identity`
107///
108/// # Optional injectables (v2)
109///
110/// After `(actor, payload)` you may add trailing parameters detected by type path:
111///
112/// - `&Event` — transport event (metadata + raw JSON)
113/// - `HandlerCtx` — delivery metadata (`event_id`, `topic_name`, `topic_key`, `seq`)
114///
115/// Unknown trailing types are rejected at compile time.
116///
117/// The handler must be `async` and return `photon::Result<()>`. Runnable: `subscribe_v2`.
118#[proc_macro_attribute]
119pub fn subscribe(attr: TokenStream, item: TokenStream) -> TokenStream {
120    subscribe::subscribe_impl(attr, item)
121}
photon_macros/lib.rs

photon_macros/
lib.rs
