refactor: events refactor (Listen, Dispatch)

[ahmed3mar]

📑 Description

Closes goravel/goravel#730

This PR introduces a modern, flexible event handling system with Listen() and Dispatch() methods, replacing the old Register()/Job() pattern. The new system supports wildcard patterns, dynamic listener registration, and seamless queue integration.

Key Features

1. Flexible Event Registration with Listen()

The new Listen() method supports multiple event formats and listener types:

// String events
app.Listen("user.created", func(event string, user User) error {
    return nil
})

// Multiple events at once
app.Listen([]string{"user.created", "user.updated"}, listener)

// Event interface types
app.Listen(&UserCreated{}, &UserCreatedListener{})

// Wildcard patterns
app.Listen("user.*", func(event string) error {
    // Handles user.created, user.updated, user.deleted, etc.
    return nil
})

Comparison with old approach:

// ❌ Old way - Rigid, ceremony-heavy
app.Register(map[event.Event][]event.Listener{
    &UserCreated{}: {&UserCreatedListener{}},
    &UserUpdated{}: {&UserCreatedListener{}}, // Same listener, must repeat
})

// ✅ New way - Flexible, concise
app.Listen([]event.Event{&UserCreated{}, &UserUpdated{}}, &UserCreatedListener{})
// Or even better with wildcards:
app.Listen("user.*", &UserCreatedListener{})

2. Direct Event Dispatching with Dispatch()

Fire events immediately and get listener responses:

// Simple dispatch
responses := app.Dispatch("user.created")

// With payload
responses := app.Dispatch("order.placed", []event.Arg{
    {Value: order, Type: "Order"},
    {Value: customer, Type: "Customer"},
})

// Responses collected from all listeners
for _, response := range responses {
    log.Info("Listener returned:", response)
}

Comparison with old approach:

// ❌ Old way - Indirect, requires Task creation
task := app.Job(event, args)
err := task.Dispatch() // No responses available

// ✅ New way - Direct with responses
responses := app.Dispatch(event, args) // Get all listener responses

3. Wildcard Pattern Support

Match multiple events with a single listener registration:

// Listen to all user events
app.Listen("user.*", func(eventName string, data any) error {
    log.Info("User event fired:", eventName)
    return nil
})

// Now all these events trigger the listener:
app.Dispatch("user.created")
app.Dispatch("user.updated")
app.Dispatch("user.deleted")
app.Dispatch("user.logged_in")

Real-world example:

// Audit logging for all admin actions
app.Listen("admin.*", &AuditLogger{})

// Security monitoring for auth events
app.Listen("auth.*", &SecurityMonitor{})

// Metrics collection for all events
app.Listen("*", &MetricsCollector{})

4. Automatic Queue Integration

Queue-aware listeners are automatically dispatched to the queue system:

type UserCreatedListener struct{}

func (l *UserCreatedListener) Handle(event any, args ...any) error {
    // Process event
    return nil
}

func (l *UserCreatedListener) ShouldQueue() bool {
    return true // Automatically queued
}

func (l *UserCreatedListener) Signature() string {
    return "UserCreatedListener"
}

func (l *UserCreatedListener) Queue(args ...any) event.Queue {
    return event.Queue{
        Connection: "redis",
        Queue:      "events",
        Enable:     true,
    }
}

// Just listen - queueing happens automatically!
app.Listen("user.created", &UserCreatedListener{})

5. Dynamic Listener Arguments

Listeners automatically receive matched arguments:

// No arguments
app.Listen("app.started", func() error {
    log.Info("App started")
    return nil
})

// Event name only
app.Listen("user.created", func(eventName string) error {
    log.Info("Event:", eventName)
    return nil
})

// Event + typed payload
app.Listen("user.created", func(eventName string, user User) error {
    log.Info("User created:", user.Email)
    return nil
})

// Variadic for all arguments
app.Listen("order.placed", func(eventName string, args ...any) error {
    // Handle variable number of arguments
    return nil
})

Migration Guide

The old Register() and Job() methods are now deprecated but still supported:

// ❌ Old Pattern (Deprecated)
app.Register(map[event.Event][]event.Listener{
    &UserCreated{}: {&EmailListener{}, &NotificationListener{}},
    &OrderPlaced{}: {&InvoiceListener{}},
})

task := app.Job(&UserCreated{}, args)
task.Dispatch()

// ✅ New Pattern (Recommended)
app.Listen(&UserCreated{}, &EmailListener{}, &NotificationListener{})
app.Listen(&OrderPlaced{}, &InvoiceListener{})

responses := app.Dispatch(&UserCreated{}, args)

Architecture Improvements

• Thread-safe: All operations use proper locking (RWMutex for registration, RLock for dispatch)
• Cached wildcard matching: Performance optimization for frequently dispatched events
• Flexible listener types: Functions, closures, structs - all supported
• Type-safe: Automatic argument type matching with reflection
• Memory efficient: Listener deduplication prevents memory leaks
• High performance: Interface assertions instead of reflection in hot paths

Backward Compatibility

• ✅ Old Register() method still works
• ✅ Old Job() method still works
• ✅ Existing Event and Listener interfaces unchanged
• ✅ All existing tests pass
• ✅ No breaking changes

✅ Checks

• Added test cases for my code

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.54%. Comparing base (bff7225) to head (52b46a8).
⚠️ Report is 129 commits behind head on master.

Files with missing lines	Patch %	Lines
event/application_dispatch.go	75.00%	25 Missing and 3 partials ⚠️
event/application_listen.go	63.15%	17 Missing and 4 partials ⚠️
event/utils.go	87.09%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1133      +/-   ##
==========================================
+ Coverage   66.81%   68.54%   +1.73%     
==========================================
  Files         214      267      +53     
  Lines       14050    15688    +1638     
==========================================
+ Hits         9387    10753    +1366     
- Misses       4287     4462     +175     
- Partials      376      473      +97     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR introduces a modern event handling system with new Listen() and Dispatch() methods, providing a more flexible and developer-friendly alternative to the existing Register()/Job() pattern. The refactor adds support for wildcard patterns, dynamic listener registration, multiple event formats, and seamless queue integration while maintaining backward compatibility.

Key Changes

• Added new Listen() method supporting string events, event interfaces, wildcards, and closures with flexible listener registration
• Added new Dispatch() method for immediate event firing with listener response collection
• Implemented thread-safe concurrent event dispatching using sync.RWMutex and sync.Map for wildcard caching

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
contracts/event/events.go	Restructured event interfaces, adding EventListener, EventQueueListener, QueueListener, Signature, and ShouldQueue interfaces; added Listen and Dispatch methods to Instance interface
event/application.go	Added new fields (listeners, mu, wildcards, wildcardsCache) to support the new event system; reorganized existing methods
event/application_dispatch.go	Implemented Dispatch method with wildcard matching, listener invocation, queue integration, and panic recovery
event/application_listen.go	Implemented Listen method supporting multiple event formats, automatic queue registration, and wildcard patterns
event/utils.go	Added dynamicQueueJob struct and getEventName helper method for event name resolution
event/utils_test.go	Added comprehensive tests for utility functions including dynamicQueueJob methods and event name resolution
event/application_test.go	Added extensive tests for Listen, Dispatch, concurrent dispatching, error recovery, and helper methods
event/task.go	Added documentation comment for eventArgsToQueueArgs function
mocks/event/*.go	Generated mock implementations for new interfaces (Signature, ShouldQueue, QueueListener, EventQueueListener, EventListener) and updated Instance mock

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The TestEventQueueListener struct is missing the required Queue method to fully implement the event.EventQueueListener interface. According to the interface definition, EventQueueListener embeds EventListener, Signature, and ShouldQueue, where the interface requires a Queue method at line 20 of contracts/event/events.go. This test struct only implements Handle, ShouldQueue, and Signature, but is missing the Queue method.

Add the missing method:

func (l *TestEventQueueListener) Queue(args ...any) event.Queue {
    return event.Queue{
        Enable:     l.ShouldQueueFunc,
        Connection: "",
        Queue:      "",
    }
}

Suggested change

	func (l *TestEventQueueListener) Queue(args ...any) event.Queue {
	return event.Queue{
	Enable: l.ShouldQueueFunc,
	Connection: "",
	Queue: "",
	}
	}

[Copilot]

Race condition: The method iterates over app.wildcards map while holding only a read lock (RLock in Dispatch), but wildcard listeners can be modified via Listen() which takes a write lock. Although Go's map iteration is safe for concurrent reads, the underlying slice wildcard (line 201) could be modified by another goroutine calling setupWildcardListen (line 125 in application_listen.go), potentially causing a race condition when appending to wildcardListeners.

While this is mitigated by the cache mechanism, consider documenting this behavior or ensuring thread safety during the iteration.

Suggested change

	wildcardListeners = append(wildcardListeners, wildcard...)
	// Make a copy of the wildcard slice to avoid race conditions
	wildcardCopy := make([]any, len(wildcard))
	copy(wildcardCopy, wildcard)
	wildcardListeners = append(wildcardListeners, wildcardCopy...)

[Copilot]

The setupEvents method registers the same listener to the queue multiple times if called repeatedly with the same listener. When Listen is called multiple times with the same EventQueueListener or QueueListener for different events, the queue.Register call (lines 99-111 and 113) will register duplicate jobs. This could lead to the listener being invoked multiple times from the queue even though it should only be registered once.

Consider tracking already-registered queue jobs or deduplicate based on Signature() before registering with the queue system.

[Copilot]

Clearing the entire wildcard cache on every wildcard listener registration is inefficient. If many wildcard listeners are registered (e.g., during application bootstrap), this will repeatedly clear and rebuild the cache. Consider a more selective cache invalidation strategy, such as only invalidating cache entries that match the new wildcard pattern, or deferring cache clearing until the next dispatch operation.

Suggested change

	// Clear cache to ensure fresh wildcard matching
	app.wildcardsCache.Range(func(key, value any) bool {
	app.wildcardsCache.Delete(key)
	return true
	})
	}
	// Selectively clear cache entries that match the new wildcard pattern
	app.wildcardsCache.Range(func(key, value any) bool {
	if wildcardMatch(eventName, key.(string)) {
	app.wildcardsCache.Delete(key)
	}
	return true
	})
	}
	// wildcardMatch checks if the eventName matches the wildcard pattern.
	// For example, pattern "user.*" matches eventName "user.created".
	func wildcardMatch(pattern, eventName string) bool {
	if !strings.Contains(pattern, "*") {
	return pattern == eventName
	}
	parts := strings.Split(pattern, "*")
	prefix := parts[0]
	return strings.HasPrefix(eventName, prefix)
	}

[Copilot]

The Job method accesses app.events map without acquiring any lock, but this map could potentially be modified by the Register method concurrently. While the current implementation of Register doesn't seem to support concurrent modification (it only assigns to the map once), accessing a map concurrently with writes can cause a runtime panic. Consider protecting this read operation with app.mu.RLock() and app.mu.RUnlock() for thread safety, consistent with how Dispatch protects its reads.

[Copilot]

The GetEvents method returns a direct reference to the internal app.events map without any locking or defensive copying. This allows external callers to modify the map concurrently, which could cause race conditions with the Register and Job methods. Consider either:

1. Protecting the access with app.mu.RLock() and returning a copy of the map, or
2. Documenting that the returned map should not be modified by callers.

Suggested change

	return app.events
	app.mu.RLock()
	defer app.mu.RUnlock()
	eventsCopy := make(map[event.Event][]event.Listener, len(app.events))
	for k, v := range app.events {
	eventsCopy[k] = v
	}
	return eventsCopy

[Copilot]

The documentation states "If a panic occurs, it returns nil", but the function silently swallows the panic without any logging or notification. This can make debugging difficult in production environments. Consider at least logging the panic before recovering, or document this behavior more explicitly as a design decision.

Example improvement:

defer func() {
    if r := recover(); r != nil {
        // Log or handle panic appropriately
        // For now, silently recover as per design
    }
}()

[Copilot]

The TestApplication_Listen tests don't cover the scenario where multiple listeners are provided in the variadic listener parameter. According to the function signature Listen(events any, listener ...any), multiple listeners could be passed, but the implementation only uses listener[0] (line 52, 55, 59, 62, 65 in application_listen.go). If this is intentional and only one listener is supported, it should be tested and documented. Otherwise, test what happens when multiple listeners are provided.

[Copilot]

The TestApplication_Dispatch tests don't verify behavior when queued listeners are dispatched. The test should include cases for:

1. Dispatching events with EventQueueListener where ShouldQueue() returns true
2. Dispatching events with QueueListener where ShouldQueue() returns true
3. Verifying that the queue's Job method is called appropriately
   This would ensure the integration between event dispatch and queue system works correctly.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Initializing sync.RWMutex{} explicitly is redundant. The zero value of sync.RWMutex is already a valid, unlocked mutex. You can simply omit this field from the initialization.

Suggested change

mu: sync.RWMutex{},

[Copilot]

When Listen() is called with multiple listeners (variadic listener ...any), only listener[0] is used. The remaining listeners are silently ignored. This could lead to bugs where developers pass multiple listeners expecting all of them to be registered. Consider either processing all listeners in the slice or documenting that only the first listener is used, or better yet, return an error if more than one listener is provided.

[Copilot]

Silent panic recovery without logging could make debugging difficult. When a listener panics, the error is completely swallowed by _ = recover(). Consider at minimum logging the panic to help developers identify and fix problematic listeners, or expose panic information through a configurable error handler.

[Copilot]

[nitpick] The documentation comment references ShouldQueue as a method name, but should clarify it refers to listeners implementing the ShouldQueue interface (with ShouldQueue() method). The current phrasing "listeners that implement ShouldQueue" could be misinterpreted. Consider: "listeners that implement the ShouldQueue interface" or "listeners with ShouldQueue() returning true".

Suggested change

	// The method automatically handles queue registration for listeners that implement ShouldQueue.
	// The method automatically handles queue registration for listeners that implement the ShouldQueue interface (i.e., those with a ShouldQueue() method).

[Copilot]

Missing test coverage for queue listeners with ShouldQueue() returning true. The tests only cover the case where ShouldQueue() returns false (lines 421-429, 431-439). Tests should verify that when ShouldQueue() returns true, the listener is properly dispatched to the queue system rather than executed synchronously. This is a critical path for the queue integration feature.

[hwbrzzl]

Thanks, amazing PR, left some questions. PTAL.

[hwbrzzl]

Can it be merged into EventQueueListener? Don't find it used elsewhere.

[hwbrzzl]

The Event prefix is duplicated with the package name.

Suggested change

	type EventQueueListener interface {
	type QueueListener interface {

[hwbrzzl]

make:listener should create a listener according to the new interface. It can be implemented in this PR or another.

[hwbrzzl]

Why add this function instead of using Listener directly?

[hwbrzzl]

The new Listen function can only support the new listener EventQueueListener for now. It doesn't need to support the old listener interface. We can notice this in the annotation, let users use the Register function for old listeners.

[hwbrzzl]

Please add all errors to errors/list.go, we will implement i18n for the error in the future.

[hwbrzzl]

The error should be returned.

[hwbrzzl]

Suggested change

	func (app *Application) queueListener(listener event.QueueListener, payload []event.Arg) any {
	func (app *Application) queueListener(listener event.QueueListener, payload []event.Arg) error {

[hwbrzzl]

Suggested change

	func (app *Application) queueEventListener(listener event.EventQueueListener, evt any, args []event.Arg) any {
	func (app *Application) queueEventListener(listener event.EventQueueListener, evt any, args []event.Arg) error {

[hwbrzzl]

Suggested change

	func (app *Application) callListener(listener any, evt any, args []event.Arg) any {
	func (app *Application) callListener(listener any, evt any, args []event.Arg) error {

[hwbrzzl]

Users have to judge each error when listening to several events. Not sure if there is a better way to optimize the action.