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 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 TypedHandler type. This ensures that the event handler receives the expected data type.

Defining a Typed Handler

First, define a handler function that expects a specific data type:

type CustomData struct {
    Value string
}

handler := func(e CustomData) error {
    fmt.Println(e.Value)
    return nil
}

Subscribing to Typed Events

Next, subscribe to the event using the Wrap function to wrap your typed handler:

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

Submitting Typed Events

When submitting events, use the AsEvent function to ensure the event is submitted with the correct type information:

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

Documentation

Index

• func AsEvent(data any) (string, any)
• func EventName(v any) string
• func RegisterEventService(s *grpc.Server, engine *Engine)
• 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 TypedHandler

Functions

func AsEvent

func AsEvent(data any) (string, any)

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

func EventName

func EventName(v any) string

EventName returns the generic event name for a given data type.

func RegisterEventService

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

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 TypedHandler

type TypedHandler[T any] func(T) error

TypedHandler is a handler that expects a specific data type.