macula_gateway_pubsub (macula v0.20.5)

Pub/Sub Handler GenServer - manages topic subscriptions and message routing.

Responsibilities: - Subscribe/unsubscribe streams to topics - Route published messages to matching subscribers - Support wildcard topics (* single-level, ** multi-level) - Track bidirectional mapping (topic ↔ stream) - Monitor stream processes for automatic cleanup

Extracted from macula_gateway.erl (Phase 3)

Summary

Types

stream_handle/0

Functions

deliver_local(Pid, Topic, Payload)

Deliver a message to LOCAL subscribers only (no remote routing). Used by pubsub_route delivery to prevent message amplification. When a message arrives from another node via pubsub_route, it should only be delivered to local subscribers, NOT re-routed to remote subscribers.

get_stream_topics(Pid, Stream)

Get all topics a stream is subscribed to.

get_subscribers(Pid, Topic)

Get all subscribers for a topic (exact and wildcard matches).

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

Handle stream process death - automatic cleanup.

init(Opts)

publish(Pid, Topic, Payload)

Publish a message to a topic (routes to matching subscribers).

start_link(Opts)

Start the pub/sub handler with options.

stop(Pid)

Stop the pub/sub handler.

subscribe(Pid, Stream, Topic)

Subscribe a stream to a topic (supports wildcards). Async (cast) to prevent blocking callers when PubSub is busy.

terminate(Reason, State)

unsubscribe(Pid, Stream, Topic)

Unsubscribe a stream from a topic. Async (cast) to prevent blocking callers when PubSub is busy.