use std::collections::BTreeSet;
use std::error::Error;
use std::fmt;
use std::time::Duration;
use crate::{
validate_consumer, validate_event_version, validate_token, AccountNames, ConsumerSpec,
LimitError, NamingError, TokenKind,
};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EventConsumer {
pub module_id: &'static str,
pub durable: &'static str,
pub filter_subjects: &'static [&'static str],
}
impl EventConsumer {
pub fn durable_name(&self) -> Result<String, NamingError> {
let base = AccountNames::module_consumer_name(self.module_id)?;
if self.durable != base
&& !self
.durable
.strip_prefix(&format!("{base}_"))
.is_some_and(|suffix| {
!suffix.is_empty()
&& suffix.bytes().all(|byte| {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_'
})
})
{
return Err(NamingError::new(
TokenKind::ModuleId,
self.durable,
"durable must belong to the module's m_{module}[_suffix] namespace",
));
}
Ok(self.durable.to_owned())
}
}
pub const EVENT_CONSUMERS: &[EventConsumer] = &[
EventConsumer {
module_id: "prefrontal-core",
durable: "m_prefrontal-core",
filter_subjects: &[
"event.broca.>",
"event.basal.flow_instance_created.v1",
"event.basal.flow_instance_extended.v1",
"event.basal.flow_instance_ended.v1",
"event.basal.flow_instance_expired.v1",
"event.basal.flow_instance_rescheduled.v1",
"event.aft.late_result_ready.v1.prefrontal-core",
"event.basal.late_result_ready.v1.prefrontal-core",
"event.cerebellum.late_result_ready.v1.prefrontal-core",
"event.fusiform.catalog_changed.v1",
"event.basal.flow_owner_notice.v1",
],
},
EventConsumer {
module_id: "astrocyte",
durable: "m_astrocyte",
filter_subjects: &[
"event.insula.>",
"event.broca.step.finished.v1",
"event.thalamus-harness.step.finished.v1",
"event.thalamus.step.finished.v1",
],
},
EventConsumer {
module_id: "prefrontal-routing",
durable: "m_prefrontal-routing",
filter_subjects: &["event.insula.>"],
},
EventConsumer {
module_id: "striatum",
durable: "m_striatum",
filter_subjects: &[
"event.insula.>",
"event.broca.route_fact.v1",
"event.thalamus-harness.route_fact.v1",
"event.colliculus.route_fact.v1",
"event.prefrontal-core.route_fact.v1",
"event.plexus.route_fact.v1",
"event.fusiform.catalog_changed.v1",
],
},
EventConsumer {
module_id: "magic-context",
durable: "m_magic-context",
filter_subjects: &[
"event.thalamus-harness.compaction.>",
"event.thalamus.compaction.>",
"event.broca.compaction.>",
],
},
EventConsumer {
module_id: "thalamus-harness",
durable: "m_thalamus-harness",
filter_subjects: &["event.magic-context.compaction.>"],
},
EventConsumer {
module_id: "thalamus",
durable: "m_thalamus",
filter_subjects: &["event.magic-context.compaction.>"],
},
EventConsumer {
module_id: "broca",
durable: "m_broca",
filter_subjects: &["event.magic-context.compaction.>"],
},
EventConsumer {
module_id: "cerebellum",
durable: "m_cerebellum",
filter_subjects: &[
"event.thalamus-harness.turn_started.v1",
"event.thalamus-harness.turn_ended.v1",
],
},
EventConsumer {
module_id: "thalamus-harness",
durable: "m_thalamus-harness_late_results",
filter_subjects: &[
"event.aft.late_result_ready.v1.thalamus-harness",
"event.cerebellum.late_result_ready.v1.thalamus-harness",
"event.basal.late_result_ready.v1.thalamus-harness",
],
},
EventConsumer {
module_id: "astrocyte",
durable: "m_astrocyte_payer",
filter_subjects: &["event.thalamus-harness.payer_row.v1"],
},
EventConsumer {
module_id: "astrocyte",
durable: "m_astrocyte_media_usage",
filter_subjects: &["event.colliculus.usage_recorded.v1"],
},
EventConsumer {
module_id: "astrocyte",
durable: "m_astrocyte_catalog",
filter_subjects: &["event.fusiform.catalog_changed.v1"],
},
EventConsumer {
module_id: "aft",
durable: "m_aft_sendstate",
filter_subjects: &["event.thalamus-harness.send_state.v1"],
},
EventConsumer {
module_id: "plexus",
durable: "m_plexus",
filter_subjects: &["event.prefrontal-core.agent_changed.v1"],
},
EventConsumer {
module_id: "wernicke",
durable: "m_wernicke_agents",
filter_subjects: &["event.prefrontal-core.agent_changed.v1"],
},
EventConsumer {
module_id: "colliculus",
durable: "m_colliculus_events",
filter_subjects: &[
"event.fusiform.catalog_changed.v1",
"event.prefrontal-core.board_changed.v1",
"event.magic-context.memory_changed.v1",
"event.thalamus-harness.turn_ended.v1",
],
},
];
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct LiveHintReader {
pub module_id: &'static str,
pub subjects: &'static [&'static str],
}
impl LiveHintReader {
pub const fn new(module_id: &'static str, subjects: &'static [&'static str]) -> Self {
Self {
module_id,
subjects,
}
}
}
pub const LIVE_HINT_READERS: &[LiveHintReader] = &[
LiveHintReader::new(
"prefrontal-routing",
&[
"event.broca.step.finished.v1",
"event.thalamus-harness.step.finished.v1",
],
),
LiveHintReader::new(
"striatum",
&[
"event.broca.step.finished.v1",
"event.thalamus-harness.step.finished.v1",
],
),
LiveHintReader::new("magic-context", &["event.astrocyte.steps_committed.v1"]),
];
pub fn live_hint_subscriptions(
account: &AccountNames,
module_id: &str,
) -> Result<Vec<String>, NamingError> {
validate_token(TokenKind::ModuleId, module_id)?;
validate_live_hint_readers(LIVE_HINT_READERS, EVENT_CONSUMERS)?;
let subjects = EVENT_CONSUMERS
.iter()
.filter(|entry| entry.module_id == module_id)
.flat_map(|entry| entry.filter_subjects)
.chain(
LIVE_HINT_READERS
.iter()
.filter(|entry| entry.module_id == module_id)
.flat_map(|entry| entry.subjects),
)
.map(|subject| {
let suffix = subject.strip_prefix("event.").ok_or_else(|| {
NamingError::new(
TokenKind::EventName,
subject,
"expected relative event subject",
)
})?;
Ok(format!("ck.{}.live.{suffix}", account.account()))
})
.collect::<Result<BTreeSet<_>, NamingError>>()?;
Ok(subjects.into_iter().collect())
}
fn validate_live_hint_readers(
entries: &[LiveHintReader],
event_consumers: &[EventConsumer],
) -> Result<(), NamingError> {
let mut modules = BTreeSet::new();
for entry in entries {
validate_token(TokenKind::ModuleId, entry.module_id)?;
if !modules.insert(entry.module_id) {
return Err(NamingError::new(
TokenKind::ModuleId,
entry.module_id,
"duplicate live-hint reader module",
));
}
if entry.subjects.is_empty() {
return Err(NamingError::new(
TokenKind::EventName,
entry.module_id,
"live-hint reader needs at least one subject",
));
}
let mut subjects = BTreeSet::new();
for subject in entry.subjects {
validate_live_hint_subject(subject)?;
if !subjects.insert(subject) {
return Err(NamingError::new(
TokenKind::EventName,
subject,
"duplicate live-hint reader subject",
));
}
for filter in event_consumers
.iter()
.filter(|consumer| consumer.module_id == entry.module_id)
.flat_map(|consumer| consumer.filter_subjects)
{
let overlaps =
crate::limits::subject_filters_overlap(subject, filter).map_err(|_| {
NamingError::new(
TokenKind::EventName,
filter,
"invalid event-consumer filter",
)
})?;
if overlaps {
return Err(NamingError::new(
TokenKind::EventName,
subject,
"live-hint subject is already covered by the module's EVENT filters",
));
}
}
}
}
Ok(())
}
fn validate_live_hint_subject(subject: &str) -> Result<(), NamingError> {
let refuse = || {
NamingError::new(
TokenKind::EventName,
subject,
"expected exact event.{module}.{name}.v{version} subject",
)
};
let relative = subject.strip_prefix("event.").ok_or_else(refuse)?;
let (module, event_version) = relative.split_once('.').ok_or_else(refuse)?;
let (event, version) = event_version.rsplit_once('.').ok_or_else(refuse)?;
validate_token(TokenKind::ModuleId, module)?;
validate_token(TokenKind::EventName, event)?;
validate_event_version(version)?;
Ok(())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AckPolicy {
Explicit,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeliverPolicy {
All,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModuleEventConsumerSpec {
pub consumer: ConsumerSpec,
pub pull: bool,
pub ack_policy: AckPolicy,
pub deliver_policy: DeliverPolicy,
pub ack_wait: Duration,
pub max_ack_pending: i64,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct DeliveryConsumerSpec {
pub consumer: ConsumerSpec,
pub pull: bool,
pub ack_policy: AckPolicy,
pub deliver_policy: DeliverPolicy,
pub ack_wait: Duration,
pub max_deliver: i64,
pub max_ack_pending: i64,
}
pub fn delivery_consumer_specs(
account: &AccountNames,
) -> Result<Vec<DeliveryConsumerSpec>, crate::LimitError> {
let names = account.streams();
let specs = [
(
names.inbox.clone(),
"m_prefrontal-core",
account.inbox_bindings(),
1,
),
(
names.core_work.clone(),
"m_prefrontal-core",
account.core_work_bindings(),
1,
),
(
names.effect_dead.clone(),
"c_ckbus_dead",
vec![account.effect_dead()],
1_000,
),
(
names.delivery_dead.clone(),
"c_ckbus_dead",
vec![account.delivery_dead()],
1_000,
),
]
.into_iter()
.map(
|(stream, durable, filter_subjects, max_ack_pending)| DeliveryConsumerSpec {
consumer: ConsumerSpec {
stream,
durable: durable.into(),
filter_subjects,
},
pull: true,
ack_policy: AckPolicy::Explicit,
deliver_policy: DeliverPolicy::All,
ack_wait: Duration::from_secs(30),
max_deliver: -1,
max_ack_pending,
},
)
.collect::<Vec<_>>();
crate::validate_consumers(
&specs
.iter()
.map(|spec| spec.consumer.clone())
.collect::<Vec<_>>(),
&crate::shipped_streams(account),
)?;
Ok(specs)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EventConsumerError {
Naming(NamingError),
Limits(LimitError),
DuplicateModule(&'static str),
DuplicateDurable(&'static str),
DurableMismatch(&'static str),
InvalidFilters(String),
}
impl fmt::Display for EventConsumerError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Naming(error) => error.fmt(f),
Self::Limits(error) => error.fmt(f),
Self::DuplicateModule(id) => write!(f, "duplicate event-consumer module {id:?}"),
Self::DuplicateDurable(name) => write!(f, "duplicate event-consumer durable {name:?}"),
Self::DurableMismatch(id) => {
write!(f, "event-consumer durable must be m_{id} or m_{id}_suffix")
}
Self::InvalidFilters(id) => {
write!(
f,
"event-consumer {id:?} needs nonempty, non-overlapping filters under event."
)
}
}
}
}
impl Error for EventConsumerError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Naming(error) => Some(error),
Self::Limits(error) => Some(error),
_ => None,
}
}
}
pub fn flow_engine_consumer_spec(
account: &AccountNames,
module_id: &str,
) -> Result<ModuleEventConsumerSpec, EventConsumerError> {
module_event_spec(account, module_id, &["event.>"])
}
pub fn event_consumer_specs(
account: &AccountNames,
) -> Result<Vec<ModuleEventConsumerSpec>, EventConsumerError> {
validate_table(EVENT_CONSUMERS)?;
EVENT_CONSUMERS
.iter()
.map(|entry| {
let mut spec = module_event_spec(account, entry.module_id, entry.filter_subjects)?;
spec.consumer.durable = entry.durable_name().map_err(EventConsumerError::Naming)?;
validate_consumer(&spec.consumer, &crate::shipped_streams(account))
.map_err(EventConsumerError::Limits)?;
Ok(spec)
})
.collect()
}
fn validate_table(entries: &[EventConsumer]) -> Result<(), EventConsumerError> {
let mut durables = BTreeSet::new();
for entry in entries {
if !durables.insert(entry.durable) {
return Err(EventConsumerError::DuplicateDurable(entry.durable));
}
if entry.durable_name().is_err() {
return Err(EventConsumerError::DurableMismatch(entry.module_id));
}
for other in entries
.iter()
.filter(|other| other.module_id.len() > entry.module_id.len())
{
let base = AccountNames::module_consumer_name(other.module_id)
.map_err(EventConsumerError::Naming)?;
if entry.durable == base || entry.durable.starts_with(&format!("{base}_")) {
return Err(EventConsumerError::DurableMismatch(entry.module_id));
}
}
validate_filters(entry.module_id, entry.filter_subjects)?;
}
Ok(())
}
fn validate_filters(module_id: &str, filters: &[&str]) -> Result<(), EventConsumerError> {
if filters.is_empty()
|| filters
.iter()
.any(|filter| !filter.starts_with("event.") || filter.len() == "event.".len())
{
return Err(EventConsumerError::InvalidFilters(module_id.to_owned()));
}
for (index, filter) in filters.iter().enumerate() {
for previous in filters.iter().take(index) {
if crate::limits::subject_filters_overlap(previous, filter)
.map_err(EventConsumerError::Limits)?
{
return Err(EventConsumerError::InvalidFilters(module_id.to_owned()));
}
}
}
Ok(())
}
fn module_event_spec(
account: &AccountNames,
module_id: &str,
filters: &[&str],
) -> Result<ModuleEventConsumerSpec, EventConsumerError> {
validate_filters(module_id, filters)?;
let consumer = ConsumerSpec {
durable: AccountNames::module_consumer_name(module_id)
.map_err(EventConsumerError::Naming)?,
stream: account.streams().event.clone(),
filter_subjects: filters
.iter()
.map(|filter| format!("ck.{}.{filter}", account.account()))
.collect(),
};
validate_consumer(&consumer, &crate::shipped_streams(account))
.map_err(EventConsumerError::Limits)?;
Ok(ModuleEventConsumerSpec {
consumer,
pull: true,
ack_policy: AckPolicy::Explicit,
deliver_policy: DeliverPolicy::All,
ack_wait: Duration::from_secs(30),
max_ack_pending: 1_000,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn live_hint_reader_table_rejects_duplicate_modules() {
let reader = LIVE_HINT_READERS[0];
let error = validate_live_hint_readers(&[reader, reader], EVENT_CONSUMERS).unwrap_err();
assert_eq!(error.kind(), TokenKind::ModuleId);
assert_eq!(error.token(), "prefrontal-routing");
assert_eq!(error.reason(), "duplicate live-hint reader module");
}
#[test]
fn live_hint_reader_table_rejects_cross_module_wildcards() {
for subjects in [&["event.*.step.finished.v1"][..], &["event.>"][..]] {
let reader = LiveHintReader::new("reader", subjects);
assert!(validate_live_hint_readers(&[reader], EVENT_CONSUMERS).is_err());
}
}
#[test]
fn live_hint_reader_table_rejects_overlap_with_own_event_filters() {
for reader in [
LiveHintReader::new("astrocyte", &["event.broca.step.finished.v1"]),
LiveHintReader::new("prefrontal-routing", &["event.insula.quota_sampled.v1"]),
] {
let error = validate_live_hint_readers(&[reader], EVENT_CONSUMERS).unwrap_err();
assert_eq!(error.token(), reader.subjects[0]);
assert_eq!(
error.reason(),
"live-hint subject is already covered by the module's EVENT filters"
);
}
}
#[test]
fn live_hint_reader_table_requires_nonempty_unique_exact_subjects() {
for subjects in [
&[][..],
&["live.broca.step.finished.v1"][..],
&["event.broca.>"][..],
&["event.broca.step.*.v1"][..],
&["event.broca.step.finished.v0"][..],
&["event.broca.step.finished.v01"][..],
&["event.broca.step.finished"][..],
&["event.broca.step.v1.finished.v1"][..],
&[
"event.broca.step.finished.v1",
"event.broca.step.finished.v1",
][..],
] {
let reader = LiveHintReader::new("reader", subjects);
assert!(
validate_live_hint_readers(&[reader], EVENT_CONSUMERS).is_err(),
"{subjects:?}"
);
}
let reader = LiveHintReader::new("reader", &["event.broca.step.finished.v1"]);
validate_live_hint_readers(&[reader], EVENT_CONSUMERS).unwrap();
let invalid_module = LiveHintReader::new("*", reader.subjects);
assert_eq!(
validate_live_hint_readers(&[invalid_module], EVENT_CONSUMERS)
.unwrap_err()
.kind(),
TokenKind::ModuleId
);
}
#[test]
fn event_consumer_table_accepts_multiple_owned_durables_per_module() {
let entry = EVENT_CONSUMERS[0];
assert_eq!(
validate_table(&[
entry,
EventConsumer {
durable: "m_prefrontal-core_other",
..entry
}
]),
Ok(())
);
}
#[test]
fn event_consumer_table_rejects_duplicate_durables() {
let entry = EVENT_CONSUMERS[0];
assert_eq!(
validate_table(&[
entry,
EventConsumer {
module_id: "other",
..entry
}
]),
Err(EventConsumerError::DuplicateDurable("m_prefrontal-core"))
);
}
#[test]
fn event_consumer_table_requires_canonical_durable_names() {
let entry = EventConsumer {
durable: "m_other",
..EVENT_CONSUMERS[0]
};
assert_eq!(
validate_table(&[entry]),
Err(EventConsumerError::DurableMismatch("prefrontal-core"))
);
for durable in [
"m_prefrontal-core_",
"m_prefrontal-core_Bad",
"m_prefrontal-core_bad-name",
"m_astrocyte_payer",
] {
assert!(validate_table(&[EventConsumer {
durable,
..EVENT_CONSUMERS[0]
}])
.is_err());
}
}
#[test]
fn event_consumer_table_refuses_another_modules_underscore_namespace() {
let owner = EventConsumer {
module_id: "owner",
durable: "m_owner_child_stolen",
filter_subjects: &["event.aft.run.v1"],
};
let child = EventConsumer {
module_id: "owner_child",
durable: "m_owner_child",
filter_subjects: &["event.aft.run.v1"],
};
assert_eq!(
validate_table(&[owner, child]),
Err(EventConsumerError::DurableMismatch("owner"))
);
}
#[test]
fn event_consumer_filters_must_be_nonempty_and_under_event() {
for filters in [
&[][..],
&["peer.>"][..],
&["event"][..],
&["event."][..],
&["> "][..],
] {
let entry = EventConsumer {
filter_subjects: filters,
..EVENT_CONSUMERS[0]
};
assert!(matches!(
validate_table(&[entry]),
Err(EventConsumerError::InvalidFilters(_))
));
}
let names = AccountNames::derive("box_readers").unwrap();
assert!(module_event_spec(&names, "reader", &["event.broca.>.run"]).is_err());
}
#[test]
fn event_consumer_filters_refuse_overlap_within_one_module() {
let names = AccountNames::derive("box_readers").unwrap();
for filters in [
&["event.insula.>", "event.*.step.finished.v1"][..],
&["event.*.step.finished.v1", "event.insula.>"][..],
&["event.runner_a.>", "event.runner_a.step.finished.v1"][..],
&[
"event.runner_a.step.finished.v1",
"event.runner_a.step.finished.v1",
][..],
] {
assert_eq!(
module_event_spec(&names, "reader", filters),
Err(EventConsumerError::InvalidFilters("reader".into())),
"{filters:?}"
);
}
assert!(module_event_spec(
&names,
"reader",
&["event.insula.>", "event.runner_a.step.finished.v1"]
)
.is_ok());
}
#[test]
fn prefrontal_core_filter_keeps_lifecycle_and_adds_delivery_events() {
let names = AccountNames::derive("box_readers").unwrap();
let reader = event_consumer_specs(&names)
.unwrap()
.into_iter()
.find(|spec| spec.consumer.durable == "m_prefrontal-core")
.expect("prefrontal-core reader is in the reviewed table");
assert_eq!(
reader.consumer.filter_subjects,
[
"ck.box_readers.event.broca.>",
"ck.box_readers.event.basal.flow_instance_created.v1",
"ck.box_readers.event.basal.flow_instance_extended.v1",
"ck.box_readers.event.basal.flow_instance_ended.v1",
"ck.box_readers.event.basal.flow_instance_expired.v1",
"ck.box_readers.event.basal.flow_instance_rescheduled.v1",
"ck.box_readers.event.aft.late_result_ready.v1.prefrontal-core",
"ck.box_readers.event.basal.late_result_ready.v1.prefrontal-core",
"ck.box_readers.event.cerebellum.late_result_ready.v1.prefrontal-core",
"ck.box_readers.event.fusiform.catalog_changed.v1",
"ck.box_readers.event.basal.flow_owner_notice.v1",
]
);
}
}