feat: add SubscriptionOnStartHandler

[alepane21]

Summary by CodeRabbit

• New Features

  • Introduced a flexible hooks system for stream subscriptions, enabling custom authorization, initial event emission, event filtering, and data mapping across NATS, Kafka, and Redis providers.
  • Added support for executing custom logic at subscription start, including emitting initial events and controlling subscription lifecycle.
  • Unified event and configuration abstractions for consistent handling across different pubsub providers.
  • Added a new module to facilitate implementing subscription start hooks with logging and callbacks.

• Bug Fixes

  • Improved consistency and structure in event data handling for NATS, Kafka, and Redis integrations.

• Tests

  • Added extensive tests covering subscription start hooks, event emission, authorization checks, and subscription lifecycle management.

• Chores

  • Updated dependencies, removed unused indirect packages, and enhanced mock generation for subscription event updaters across pubsub providers.

Depends on engine PR: wundergraph/graphql-go-tools#1243

How to use the new hook?

The hook implemented in this PR is the SubscriptionOnStartHandler as defined here:

cosmo/router/core/subscriptions_modules.go

Line 107 in ceac255

type SubscriptionOnStartHandler interface {

Example

Query

On the demo graph, we will create a module that add some logic to the following query

employeeUpdatedMyKafka(employeeID: $employeeID)

Module code that implement the new hook

As an example, this module will emit a message if the subscription is started with employeeID == 1.

const myModuleID = "startSubscriptionModule"

type StartSubscriptionModule struct {}

func (m *StartSubscriptionModule) SubscriptionOnStart(ctx core.SubscriptionOnStartHookContext) (bool, error) {
    if ctx.SubscriptionEventConfiguration().RootFieldName() != "employeeUpdatedMyKafka" {
      return false, nil
    }
    employeeId := ctx.RequestContext().Operation().Variables().GetInt64("employeeID")
    if employeeId != 1 {
        return false, nil
    }
    ctx.WriteEvent(&kafka.Event{
        Data: []byte(`{"id": 1, "__typename": "Employee"}`),
    })
    return false, nil
}

func (m *StartSubscriptionModule) Module() core.ModuleInfo {
	return core.ModuleInfo{
		// This is the ID of your module, it must be unique
		ID: myModuleID,
		// The priority of your module, lower numbers are executed first
		Priority: 1,
		New: func() core.Module {
			return &StartSubscriptionModule{}
		},
	}
}

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/cosmo-docs.
• I have read the Contributors Guide.