beacon

README

Beacon

Beacon is a lightweight event handling engine for Go, designed to manage event handlers in a context-aware manner. It supports both local event handling and remote event submission via gRPC.

Features

• Context-aware event handling
• Support for remote event submission via gRPC
• Easy-to-use API for subscribing and submitting events
• Functional options for configuration
• Optional use of generics for type-safe event handling

Usage

Creating an Engine

To create a new event handling engine, use the New function:

import "github.com/yonedash/beacon"

engine := beacon.New()

Subscribing to Events

To subscribe to an event, use the Subscribe method:

handler := func(event beacon.Event) error {
    // Handle the event
    return nil
}

engine.Subscribe("event_name", handler)

Submitting Events

To submit an event, use the Submit method:

err := engine.Submit("event_name", eventData)
if err != nil {
    // Handle error
}

Remote Event Submission

Beacon supports submitting events to a remote server using gRPC. This is useful for distributed systems where events need to be processed by a central server.

Setting Up the Remote Server

First, you need to set up a gRPC server that can receive events. Use the RegisterEventService function to register the event service with your gRPC server:

import (
    "net"
    "google.golang.org/grpc"
    "github.com/yonedash/beacon"
)

func main() {
    addr := "127.0.0.1:8941"
    lis, err := net.Listen("tcp", addr)
    if err != nil {
        log.Fatal(err)
    }

    s := grpc.NewServer()
    engine := beacon.New()
    beacon.RegisterEventService(s, engine)

    if err := s.Serve(lis); err != nil {
        log.Fatal(err)
    }
}

Submitting Events to the Remote Server

To submit events to the remote server, create a gRPC client connection and configure the engine to use it:

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "github.com/yonedash/beacon"
)

func main() {
    conn, err := grpc.Dial("127.0.0.1:8941", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    engine := beacon.New(beacon.WithRemote(conn))

    err = engine.Submit("event_name", eventData)
    if err != nil {
        // Handle error
    }
}

Receiving Remote Events

To handle events received from a remote client, you need to subscribe to the events on the server side. The server will automatically call the appropriate handlers when events are received.

Subscribing to Events on the Server

import (
    "github.com/yonedash/beacon"
)

func main() {
    engine := beacon.New()

    handler := func(event beacon.Event) error {
        // Handle the event
        return nil
    }

    engine.Subscribe("event_name", handler)

    // Set up and start the gRPC server as shown in the previous section
}

When a remote client submits an event, the server will deserialize the event data and call the subscribed handlers.

Optional Use of Generics

Beacon also supports the optional use of generics for type-safe event handling. This can be useful for ensuring that event handlers receive the expected data type. However, using generics is optional.

Using Generics with Events

To use generics with events, you can wrap your handler using the Wrap function and TypedEvent type:

type CustomData struct {
    Value string
}

handler := func(e beacon.TypedEvent[CustomData]) error {
    if e.Data.Value != "test" {
        t.Errorf("expected 'test', got '%s'", e.Data.Value)
    }
    return nil
}

engine := beacon.New()
engine.Subscribe(beacon.Wrap(handler))

data := CustomData{Value: "test"}
if err := engine.Submit(beacon.Typed(data)); err != nil {
    // Handle error
}

Documentation

Index

• func RegisterEventService(s *grpc.Server, engine *Engine)
• func Typed(data any) (string, any)
• type Engine
  • func New(opts ...Option) *Engine
  • func (s *Engine) Size() int
  • func (s *Engine) Submit(eventName string, data any) error
  • func (s *Engine) SubmitWithContext(ctx context.Context, eventName string, data any) error
  • func (s *Engine) Subscribe(eventName string, handler Handler)
• type Event
  • func (e Event) Cancel()
• type Handler
  • func Wrap[T any](handler TypedHandler[T]) (string, Handler)
• type Option
  • func WithRemote(conn *grpc.ClientConn) Option
• type TypedEvent
• type TypedHandler

Functions

func RegisterEventService

func RegisterEventService(s *grpc.Server, engine *Engine)

func Typed

func Typed(data any) (string, any)

Typed returns the generic event name and data. Usage: engine.Submit(beacon.Typed(data))

Types

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine manages event handlers that are triggered in a context-aware manner.

func New

func New(opts ...Option) *Engine

New creates an instance of Show to manage event handlers.

func (*Engine) Size

func (s *Engine) Size() int

Size returns the number of registered handlers for an event name.

func (*Engine) Submit

func (s *Engine) Submit(eventName string, data any) error

Submit invokes the handler functions when an event is submitted.

func (*Engine) SubmitWithContext

func (s *Engine) SubmitWithContext(ctx context.Context, eventName string, data any) error

SubmitWithContext invokes the handler functions when an event is submitted with a context.

func (*Engine) Subscribe

func (s *Engine) Subscribe(eventName string, handler Handler)

Subscribe adds a handler function for a specific event name. Event names must be non-empty strings.

type Event

type Event struct {
	Context   context.Context
	Timestamp time.Time
	Data      any
	// contains filtered or unexported fields
}

Event represents a data structure that is passed to event handlers.

func (Event) Cancel

func (e Event) Cancel()

Cancel stops propagation of the event to further handlers.

type Handler

type Handler func(Event) error

Handler is a function that processes an event.

func Wrap

func Wrap[T any](handler TypedHandler[T]) (string, Handler)

Wrap wraps a handler that expects a specific data type.

type Option

type Option func(*Engine)

Option is a functional option for configuring a Engine instance.

func WithRemote

func WithRemote(conn *grpc.ClientConn) Option

WithRemote configures the Show instance to send events to a remote server using gRPC.

type TypedEvent

type TypedEvent[T any] struct {
	Event
	Data T
}

TypedEvent is an event that contains a specific data type.

type TypedHandler

type TypedHandler[T any] func(TypedEvent[T]) error

TypedHandler is a handler that expects a specific data type.