cerouter

README

cerouter

Package cerouter provides a router for CloudEvents.

Get started

Install cerouter.

go get github.com/injustease/cerouter

Import the module into your code.

import "github.com/injustease/cerouter"

While the Go SDK for CloudEvents provides multiple signature for the receiver, this package only support one of them.

type Handler func(context.Context, cloudevents.Event) (*cloudevents.Event, error)

Default router.

func main() {
    r := cerouter.New() // default router will filter event by type
    r.Handle("com.example.ping", handlePing)
    r.Handle("com.example.pong", handlePong)

    c, err := cloudevents.NewClientHTTP()
    if err != nil {
        log.Fatalf("failed to create client, %v", err)
    }

    log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

func handlePing(ctx context.Context, event cloudevents.Event) (*cloudevents.Event, error) {
    // handle ping
}

func handlePong(ctx context.Context, event cloudevents.Event) (*cloudevents.Event, error) {
    // handle pong
}

You can specify which context attribute to filter.

func main() {
    typeRouter := cerouter.New(cerouter.WithType()) // filter event by type, same as default one
    typeRouter.Handle("com.example.ping", handlePing)

    sourceRouter := cerouter.New(cerouter.WithSource()) // filter event by source
    sourceROuter.Handle("github.com/injustease/cerouter")

    subjectRouter := cerouter.New(cerouter.WithSubject()) // filter event by subject
    subjectRouter.Handle("cerouter", handlePing)

    extensionRouter := cerouter.New(cerouter.WithExtension("extkey")) // filter event by extension
    extensionRouter.Handle("extval", handlePing)
}

Example

Run the following code, it will starting HTTP server with default port :8080 and default path /.

package main

import (
    "context"
    "fmt"
    "log"

    cloudevents "github.com/cloudevents/sdk-go/v2"
    "github.com/injustease/cerouter"
)

func main() {
    r := cerouter.New(cerouter.WithType())
    r.Handle("com.example.ping", func(ctx context.Context, e cloudevents.Event) (*cloudevents.Event, error) {
        fmt.Println(e)
        return nil, nil
    })

    c, err := cloudevents.NewClientHTTP()
    if err != nil {
        log.Fatal(err)
    }
    log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

Try to send the event.

curl -v "localhost:8080" \
-X POST \
-H "Ce-Id: unique-id" \
-H "Ce-Specversion: 1.0" \
-H "Ce-Type: com.example.ping" \
-H "Ce-Source: github.com/injustease/cerouter" \
-H "Ce-Subject: cerouter" \
-H "Ce-Extkey: extval" \
-H "Content-Type: application/json" \
-d '{"msg":"Hello from cerouter!"}'

Documentation

Overview

Package cerouter provides a router for CloudEvent receiver.

Get Started

Install cerouter.

go get github.com/injustease/cerouter

Import the module into your code.

import "github.com/injustease/cerouter"

While the Go SDK for CloudEvents https://github.com/cloudevents/sdk-go provides multiple signature for the receiver see: https://github.com/cloudevents/sdk-go/blob/main/v2/client/client.go#L33-L50, this package only support one of them.

type Handler func(context.Context, cloudevents.Event) (*cloudevents.Event, error)

Default router.

func main() {
	r := cerouter.New() // default router will filter event by type
	r.Handle("com.example.ping", handlePing)
	r.Handle("com.example.pong", handlePong)

	c, err := cloudevents.NewClientHTTP()
	if err != nil {
		log.Fatalf("failed to create client, %v", err)
	}

	log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

func handlePing(ctx context.Context, event cloudevents.Event) (*cloudevents.Event, error) {
	// handle ping
}

func handlePong(ctx context.Context, event cloudevents.Event) (*cloudevents.Event, error) {
	// handle pong
}

You can specify which context attribute to filter.

func main() {
	typeRouter := cerouter.New(cerouter.WithType()) // filter event by type, same as default one
	typeRouter.Handle("com.example.ping", handlePing)

	sourceRouter := cerouter.New(cerouter.WithSource()) // filter event by source
	sourceROuter.Handle("github.com/injustease/cerouter")

	subjectRouter := cerouter.New(cerouter.WithSubject()) // filter event by subject
	subjectRouter.Handle("cerouter", handlePing)

	extensionRouter := cerouter.New(cerouter.WithExtension("extkey")) // filter event by extension
	extensionRouter.Handle("extval", handlePing)
}

Example

Run the following code, it will starting HTTP server with default port `:8080` and default path `/`.

package main

import (
	"context"
	"fmt"
	"log"

	cloudevents "github.com/cloudevents/sdk-go/v2"
	"github.com/injustease/cerouter"
)

func main() {
	r := cerouter.New(cerouter.WithType())
	r.Handle("com.example.ping", func(ctx context.Context, e cloudevents.Event) (*cloudevents.Event, error) {
		fmt.Println(e)
		return nil, nil
	})

	c, err := cloudevents.NewClientHTTP()
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

Try to send the event.

curl -v "localhost:8080" \
-X POST \
-H "Ce-Id: unique-id" \
-H "Ce-Specversion: 1.0" \
-H "Ce-Type: com.example.ping" \
-H "Ce-Source: github.com/injustease/cerouter" \
-H "Ce-Subject: cerouter" \
-H "Ce-Extkey: extval" \
-H "Content-Type: application/json" \
-d '{"msg":"Hello from cerouter!"}'

Index

• type Handler
• type Option
  • func WithExtension(ext string) Option
  • func WithSource() Option
  • func WithSubject() Option
  • func WithType() Option
• type Router
  • func New(opts ...Option) *Router
  • func (r *Router) Handle(filter string, handler Handler)
  • func (r *Router) Receiver() Handler

Examples

• WithExtension
• WithSource
• WithSubject
• WithType

Types

type Handler

type Handler func(context.Context, cloudevents.Event) (*cloudevents.Event, error)

Handler is the function signature for CloudEvent receiver.

type Option

type Option func(*Router)

Option configures the Router.

func WithExtension

func WithExtension(ext string) Option

WithExtension configures the Router to filter by extension.

Example

package main

import (
	"context"
	"fmt"
	"log"

	cloudevents "github.com/cloudevents/sdk-go/v2"
	"github.com/injustease/cerouter"
)

func main() {
	r := cerouter.New(cerouter.WithExtension("extkey"))
	r.Handle("extval", func(ctx context.Context, e cloudevents.Event) (*cloudevents.Event, error) {
		fmt.Println(e)
		return nil, nil
	})

	c, err := cloudevents.NewClientHTTP()
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

func WithSource

func WithSource() Option

WithSource configures the Router to filter by source.

Example

package main

import (
	"context"
	"fmt"
	"log"

	cloudevents "github.com/cloudevents/sdk-go/v2"
	"github.com/injustease/cerouter"
)

func main() {
	r := cerouter.New(cerouter.WithSource())
	r.Handle("github.com/injustease/cerouter", func(ctx context.Context, e cloudevents.Event) (*cloudevents.Event, error) {
		fmt.Println(e)
		return nil, nil
	})

	c, err := cloudevents.NewClientHTTP()
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

func WithSubject

func WithSubject() Option

WithSubject configures the Router to filter by subject.

Example

package main

import (
	"context"
	"fmt"
	"log"

	cloudevents "github.com/cloudevents/sdk-go/v2"
	"github.com/injustease/cerouter"
)

func main() {
	r := cerouter.New(cerouter.WithSubject())
	r.Handle("cerouter", func(ctx context.Context, e cloudevents.Event) (*cloudevents.Event, error) {
		fmt.Println(e)
		return nil, nil
	})

	c, err := cloudevents.NewClientHTTP()
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

func WithType

func WithType() Option

WithType configures the Router to filter by type.

Example

package main

import (
	"context"
	"fmt"
	"log"

	cloudevents "github.com/cloudevents/sdk-go/v2"
	"github.com/injustease/cerouter"
)

func main() {
	r := cerouter.New(cerouter.WithType())
	r.Handle("com.example.ping", func(ctx context.Context, e cloudevents.Event) (*cloudevents.Event, error) {
		fmt.Println(e)
		return nil, nil
	})

	c, err := cloudevents.NewClientHTTP()
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(c.StartReceiver(context.TODO(), r.Receiver()))
}

type Router

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

Router is a CloudEvent router which can dispatch CloudEvent by its context attribute. Zero value Router is a ready to use router. Default filter is filter by type.

func New

func New(opts ...Option) *Router

New returns an initialized Router and accept optional Option. New without Option is the same as using zero value Router. Configure filter by other context attribute using Option, for example.

r := cerouter.New(cerouter.WithSource())

func (*Router) Handle

func (r *Router) Handle(filter string, handler Handler)

Handle registers the handler for the given filter.

func (*Router) Receiver

func (r *Router) Receiver() Handler

Receiver returns a Handler to be used by CloudEvent receiver.