Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(engine): typed event hierarchy + EventBus with fanout + AuditSubscriber + Engine
CarterPerez-dev2ba81cfd8263
diff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/audit_subscriber_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/audit_subscriber_spec.crnew file mode 100644index 00000000..8db93e9f--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/audit_subscriber_spec.cr@@ -0,0 +1,62 @@+# ===================+# ©AngelaMos | 2026+# audit_subscriber_spec.cr+# ===================++require "../../spec_helper"+require "../../../src/cre/engine/event_bus"+require "../../../src/cre/engine/subscribers/audit_subscriber"+require "../../../src/cre/audit/audit_log"+require "../../../src/cre/persistence/sqlite/sqlite_persistence"+require "../../../src/cre/events/credential_events"++describe CRE::Engine::Subscribers::AuditSubscriber do+ it "writes RotationCompleted events to the audit log" do+ persist = CRE::Persistence::Sqlite::SqlitePersistence.new(":memory:")+ persist.migrate!+ log = CRE::Audit::AuditLog.new(persist, Bytes.new(32, 0_u8), 1, 1024)++ bus = CRE::Engine::EventBus.new+ sub = CRE::Engine::Subscribers::AuditSubscriber.new(bus, log)+ sub.start+ bus.run++ cred_id = UUID.random+ rot_id = UUID.random+ bus.publish(CRE::Events::RotationCompleted.new(cred_id, rot_id))+ sleep 0.1.seconds++ persist.audit.latest_seq.should eq 1_i64+ entry = persist.audit.range(1_i64, 1_i64).first+ entry.event_type.should eq "rotation.completed"+ entry.target_id.should eq cred_id+ ensure+ bus.try(&.stop)+ sub.try(&.stop)+ persist.try(&.close)+ end++ it "writes multiple event types correctly" do+ persist = CRE::Persistence::Sqlite::SqlitePersistence.new(":memory:")+ persist.migrate!+ log = CRE::Audit::AuditLog.new(persist, Bytes.new(32, 0_u8), 1, 1024)+ bus = CRE::Engine::EventBus.new+ sub = CRE::Engine::Subscribers::AuditSubscriber.new(bus, log)+ sub.start+ bus.run++ cred_id = UUID.random+ bus.publish(CRE::Events::PolicyViolation.new(cred_id, "test-policy", "stale"))+ bus.publish(CRE::Events::DriftDetected.new(cred_id, "h1", "h2"))+ sleep 0.1.seconds++ persist.audit.latest_seq.should eq 2_i64+ entries = persist.audit.range(1_i64, 2_i64)+ entries.map(&.event_type).should eq ["policy.violation", "drift.detected"]+ log.verify_chain.should be_true+ ensure+ bus.try(&.stop)+ sub.try(&.stop)+ persist.try(&.close)+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/engine_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/engine_spec.crnew file mode 100644index 00000000..b9e7bee3--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/engine_spec.cr@@ -0,0 +1,42 @@+# ===================+# ©AngelaMos | 2026+# engine_spec.cr+# ===================++require "../../spec_helper"+require "../../../src/cre/engine/engine"+require "../../../src/cre/persistence/sqlite/sqlite_persistence"+require "../../../src/cre/events/credential_events"++describe CRE::Engine::Engine do+ it "boots, accepts events, and shuts down cleanly" do+ persist = CRE::Persistence::Sqlite::SqlitePersistence.new(":memory:")+ persist.migrate!++ engine = CRE::Engine::Engine.new(persist, Bytes.new(32, 0_u8))+ engine.start++ cred_id = UUID.random+ rot_id = UUID.random+ engine.bus.publish(CRE::Events::RotationCompleted.new(cred_id, rot_id))+ sleep 0.1.seconds++ persist.audit.latest_seq.should eq 1_i64+ engine.audit_log.verify_chain.should be_true++ engine.stop+ ensure+ persist.try(&.close)+ end++ it "raises if started twice" do+ persist = CRE::Persistence::Sqlite::SqlitePersistence.new(":memory:")+ persist.migrate!+ engine = CRE::Engine::Engine.new(persist, Bytes.new(32, 0_u8))+ engine.start+ expect_raises(Exception, "already started") { engine.start }+ engine.stop+ ensure+ persist.try(&.close)+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/event_bus_spec.cr b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/event_bus_spec.crnew file mode 100644index 00000000..0b10fa1c--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/spec/unit/engine/event_bus_spec.cr@@ -0,0 +1,91 @@+# ===================+# ©AngelaMos | 2026+# event_bus_spec.cr+# ===================++require "../../spec_helper"+require "../../../src/cre/engine/event_bus"+require "../../../src/cre/events/system_events"++describe CRE::Engine::EventBus do+ it "delivers events to subscribers" do+ bus = CRE::Engine::EventBus.new+ bus.run+ received = [] of String+ received_mutex = Mutex.new+ ch = bus.subscribe(buffer: 16, overflow: CRE::Engine::EventBus::Overflow::Block)+ spawn do+ loop do+ ev = ch.receive+ received_mutex.synchronize { received << ev.class.name }+ rescue Channel::ClosedError+ break+ end+ end++ bus.publish(CRE::Events::AlertRaised.new(severity: CRE::Events::Severity::Warn, message: "hi"))+ sleep 0.1.seconds++ received_mutex.synchronize { received.should contain("CRE::Events::AlertRaised") }+ ensure+ bus.try(&.stop)+ end++ it "fans out to multiple subscribers" do+ bus = CRE::Engine::EventBus.new+ bus.run++ counter1 = Atomic(Int32).new(0)+ counter2 = Atomic(Int32).new(0)+ ch1 = bus.subscribe+ ch2 = bus.subscribe+ spawn do+ loop do+ ch1.receive+ counter1.add(1)+ rescue Channel::ClosedError+ break+ end+ end+ spawn do+ loop do+ ch2.receive+ counter2.add(1)+ rescue Channel::ClosedError+ break+ end+ end++ 3.times { bus.publish(CRE::Events::SchedulerTick.new) }+ sleep 0.1.seconds++ counter1.get.should eq 3+ counter2.get.should eq 3+ ensure+ bus.try(&.stop)+ end++ it "drops on Drop overflow when subscriber is slow" do+ bus = CRE::Engine::EventBus.new+ bus.run+ ch = bus.subscribe(buffer: 1, overflow: CRE::Engine::EventBus::Overflow::Drop)+ 5.times { bus.publish(CRE::Events::SchedulerTick.new) }+ sleep 0.1.seconds+ # The slow subscriber's channel buffered at most 1 event; rest were dropped.+ # Drain non-blocking: we should be able to take 0 or 1 event before it would block.+ delivered = 0+ drained = false+ until drained+ select+ when ch.receive+ delivered += 1+ else+ drained = true+ end+ end+ delivered.should be <= 5+ delivered.should be < 5 # at least one was dropped+ ensure+ bus.try(&.stop)+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/engine.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/engine.crnew file mode 100644index 00000000..ba9b5c9e--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/engine.cr@@ -0,0 +1,49 @@+# ===================+# ©AngelaMos | 2026+# engine.cr+# ===================++require "log"+require "./event_bus"+require "./subscribers/audit_subscriber"+require "../audit/audit_log"+require "../persistence/persistence"++module CRE::Engine+ class Engine+ Log = ::Log.for("cre.engine")++ getter bus : EventBus+ getter persistence : Persistence::Persistence+ getter audit_log : Audit::AuditLog++ @audit_subscriber : Subscribers::AuditSubscriber+ @started : Bool++ def initialize(@persistence : Persistence::Persistence, hmac_key : Bytes, hmac_version : Int32 = 1, ratchet_every : Int32 = 1024)+ @bus = EventBus.new+ @audit_log = Audit::AuditLog.new(@persistence, hmac_key, hmac_version, ratchet_every)+ @audit_subscriber = Subscribers::AuditSubscriber.new(@bus, @audit_log)+ @started = false+ end++ def start : Nil+ raise "engine already started" if @started+ @started = true+ @audit_subscriber.start+ @bus.run+ Log.info { "engine started" }+ end++ def stop : Nil+ return unless @started+ Log.info { "engine stopping" }+ @bus.publish(Events::ShutdownRequested.new) rescue nil+ sleep 0.05.seconds # let subscribers see it+ @audit_subscriber.stop+ @bus.stop+ @started = false+ Log.info { "engine stopped" }+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/event_bus.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/event_bus.crnew file mode 100644index 00000000..960e5ac4--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/event_bus.cr@@ -0,0 +1,80 @@+# ===================+# ©AngelaMos | 2026+# event_bus.cr+# ===================++require "log"+require "../events/event"++module CRE::Engine+ class EventBus+ Log = ::Log.for("cre.event_bus")++ enum Overflow+ Block+ Drop+ end++ record Subscription, channel : Channel(Events::Event), overflow : Overflow++ @inbox : Channel(Events::Event)+ @subs : Array(Subscription)+ @subs_mutex : Mutex+ @running : Bool++ def initialize(inbox_capacity : Int32 = 1024)+ @inbox = Channel(Events::Event).new(capacity: inbox_capacity)+ @subs = [] of Subscription+ @subs_mutex = Mutex.new+ @running = false+ end++ def subscribe(buffer : Int32 = 64, overflow : Overflow = Overflow::Block) : Channel(Events::Event)+ ch = Channel(Events::Event).new(capacity: buffer)+ @subs_mutex.synchronize { @subs << Subscription.new(ch, overflow) }+ ch+ end++ def publish(event : Events::Event) : Nil+ @inbox.send(event)+ end++ def run : Nil+ @running = true+ spawn(name: "event-bus") do+ while @running+ begin+ ev = @inbox.receive+ rescue Channel::ClosedError+ break+ end+ @subs_mutex.synchronize { @subs.dup }.each { |s| dispatch(s, ev) }+ end+ end+ end++ def stop : Nil+ @running = false+ @inbox.close+ @subs_mutex.synchronize do+ @subs.each(&.channel.close)+ end+ end++ private def dispatch(sub : Subscription, ev : Events::Event) : Nil+ case sub.overflow+ in Overflow::Block+ sub.channel.send(ev)+ in Overflow::Drop+ select+ when sub.channel.send(ev)+ # delivered+ else+ Log.warn { "subscriber drop: #{ev.class.name}" }+ end+ end+ rescue Channel::ClosedError+ # subscriber gone; remove from list lazily on next dispatch+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/subscribers/audit_subscriber.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/subscribers/audit_subscriber.crnew file mode 100644index 00000000..fab3eb8c--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/engine/subscribers/audit_subscriber.cr@@ -0,0 +1,85 @@+# ===================+# ©AngelaMos | 2026+# audit_subscriber.cr+# ===================++require "../event_bus"+require "../../audit/audit_log"+require "../../events/credential_events"+require "../../events/system_events"++module CRE::Engine::Subscribers+ class AuditSubscriber+ @ch : Channel(Events::Event)?+ @running : Bool++ def initialize(@bus : EventBus, @log : Audit::AuditLog, @actor : String = "system")+ @running = false+ end++ def start : Nil+ @running = true+ ch = @bus.subscribe(buffer: 256, overflow: EventBus::Overflow::Block)+ @ch = ch+ spawn(name: "audit-sub") do+ while @running+ begin+ ev = ch.receive+ rescue Channel::ClosedError+ break+ end+ handle(ev)+ end+ end+ end++ def stop : Nil+ @running = false+ @ch.try(&.close)+ end++ private def handle(ev : Events::Event) : Nil+ case ev+ when Events::RotationCompleted+ @log.append("rotation.completed", @actor, ev.credential_id, {+ "rotation_id" => ev.rotation_id.to_s,+ })+ when Events::RotationFailed+ @log.append("rotation.failed", @actor, ev.credential_id, {+ "rotation_id" => ev.rotation_id.to_s,+ "reason" => ev.reason,+ })+ when Events::RotationStepCompleted+ @log.append("rotation.step.completed", @actor, ev.credential_id, {+ "rotation_id" => ev.rotation_id.to_s,+ "step" => ev.step.to_s,+ })+ when Events::RotationStepFailed+ @log.append("rotation.step.failed", @actor, ev.credential_id, {+ "rotation_id" => ev.rotation_id.to_s,+ "step" => ev.step.to_s,+ "error" => ev.error,+ })+ when Events::PolicyViolation+ @log.append("policy.violation", @actor, ev.credential_id, {+ "policy_name" => ev.policy_name,+ "reason" => ev.reason,+ })+ when Events::DriftDetected+ @log.append("drift.detected", @actor, ev.credential_id, {+ "expected_hash" => ev.expected_hash,+ "actual_hash" => ev.actual_hash,+ })+ when Events::CredentialDiscovered+ @log.append("credential.discovered", @actor, ev.credential_id, {} of String => String)+ when Events::AlertRaised+ @log.append("alert.raised", @actor, nil, {+ "severity" => ev.severity.to_s,+ "message" => ev.message,+ })+ end+ rescue ex+ EventBus::Log.error(exception: ex) { "audit subscriber failed to write" }+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/credential_events.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/credential_events.crnew file mode 100644index 00000000..0ac959de--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/credential_events.cr@@ -0,0 +1,100 @@+# ===================+# ©AngelaMos | 2026+# credential_events.cr+# ===================++require "uuid"+require "./event"++module CRE::Events+ abstract class CredentialEvent < Event+ getter credential_id : UUID++ def initialize(@credential_id : UUID)+ super()+ end+ end++ class CredentialDiscovered < CredentialEvent+ end++ class PolicyViolation < CredentialEvent+ getter policy_name : String+ getter reason : String++ def initialize(credential_id : UUID, @policy_name : String, @reason : String)+ super(credential_id)+ end+ end++ class RotationScheduled < CredentialEvent+ getter rotator_kind : String++ def initialize(credential_id : UUID, @rotator_kind : String)+ super(credential_id)+ end+ end++ class RotationStarted < CredentialEvent+ getter rotation_id : UUID+ getter rotator_kind : String++ def initialize(credential_id : UUID, @rotation_id : UUID, @rotator_kind : String)+ super(credential_id)+ end+ end++ class RotationStepStarted < CredentialEvent+ getter rotation_id : UUID+ getter step : Symbol++ def initialize(credential_id : UUID, @rotation_id : UUID, @step : Symbol)+ super(credential_id)+ end+ end++ class RotationStepCompleted < CredentialEvent+ getter rotation_id : UUID+ getter step : Symbol++ def initialize(credential_id : UUID, @rotation_id : UUID, @step : Symbol)+ super(credential_id)+ end+ end++ class RotationStepFailed < CredentialEvent+ getter rotation_id : UUID+ getter step : Symbol+ getter error : String++ def initialize(credential_id : UUID, @rotation_id : UUID, @step : Symbol, @error : String)+ super(credential_id)+ end+ end++ class RotationCompleted < CredentialEvent+ getter rotation_id : UUID++ def initialize(credential_id : UUID, @rotation_id : UUID)+ super(credential_id)+ end+ end++ class RotationFailed < CredentialEvent+ getter rotation_id : UUID+ getter reason : String++ def initialize(credential_id : UUID, @rotation_id : UUID, @reason : String)+ super(credential_id)+ end+ end++ class DriftDetected < CredentialEvent+ getter expected_hash : String+ getter actual_hash : String++ def initialize(credential_id : UUID, @expected_hash : String, @actual_hash : String)+ super(credential_id)+ end+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/event.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/event.crnew file mode 100644index 00000000..53b3ca6c--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/event.cr@@ -0,0 +1,13 @@+# ===================+# ©AngelaMos | 2026+# event.cr+# ===================++require "uuid"++module CRE::Events+ abstract class Event+ getter id : UUID = UUID.random+ getter occurred_at : Time = Time.utc+ end+enddiff --git a/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/system_events.cr b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/system_events.crnew file mode 100644index 00000000..9b75e305--- /dev/null+++ b/PROJECTS/intermediate/credential-rotation-enforcer/src/cre/events/system_events.cr@@ -0,0 +1,29 @@+# ===================+# ©AngelaMos | 2026+# system_events.cr+# ===================++require "./event"++module CRE::Events+ enum Severity+ Info+ Warn+ Critical+ end++ class AlertRaised < Event+ getter severity : Severity+ getter message : String++ def initialize(@severity : Severity, @message : String)+ super()+ end+ end++ class SchedulerTick < Event+ end++ class ShutdownRequested < Event+ end+end