http

README

Dapr HTTP Service SDK for Go

Start by importing Dapr Go service/http package:

daprd "github.com/dapr/go-sdk/service/http"

Creating and Starting Service

To create an HTTP Dapr service, first, create a Dapr callback instance with a specific address:

s := daprd.NewService(":8080")

Or with address and an existing http.ServeMux in case you want to combine existing server implementations:

mux := http.NewServeMux()
mux.HandleFunc("/", myOtherHandler)
s := daprd.NewServiceWithMux(":8080", mux)

Once you create a service instance, you can "attach" to that service any number of event, binding, and service invocation logic handlers as shown below. Onces the logic is defined, you are ready to start the service:

if err := s.Start(); err != nil && err != http.ErrServerClosed {
	log.Fatalf("error: %v", err)
}

Event Handling

To handle events from specific topic you need to add at least one topic event handler before starting the service:

sub := &common.Subscription{
	PubsubName: "messages",
	Topic: "topic1",
	Route: "/events",
}
err := s.AddTopicEventHandler(sub, eventHandler)
if err != nil {
	log.Fatalf("error adding topic subscription: %v", err)
}

The handler method itself can be any method with the expected signature:

func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
	log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
	// do something with the event
	return true, nil
}

Service Invocation Handler

To handle service invocations you will need to add at least one service invocation handler before starting the service:

if err := s.AddServiceInvocationHandler("/echo", echoHandler); err != nil {
	log.Fatalf("error adding invocation handler: %v", err)
}

The handler method itself can be any method with the expected signature:

func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.Content, err error) {
	log.Printf("echo - ContentType:%s, Verb:%s, QueryString:%s, %+v", in.ContentType, in.Verb, in.QueryString, string(in.Data))
	// do something with the invocation here 
	out = &common.Content{
		Data:        in.Data,
		ContentType: in.ContentType,
		DataTypeURL: in.DataTypeURL,
	}
	return
}

Binding Invocation Handler

To handle binding invocations you will need to add at least one binding invocation handler before starting the service:

if err := s.AddBindingInvocationHandler("/run", runHandler); err != nil {
	log.Fatalf("error adding binding handler: %v", err)
}

The handler method itself can be any method with the expected signature:

func runHandler(ctx context.Context, in *common.BindingEvent) (out []byte, err error) {
	log.Printf("binding - Data:%v, Meta:%v", in.Data, in.Metadata)
	// do something with the invocation here 
	return nil, nil
}

Templates

To accelerate your HTTP Dapr app development in Go even further you can use one of the GitHub templates integrating the HTTP Dapr callback package:

• Dapr HTTP Event Subscriber in Go - Template project to jump start your Dapr event subscriber service with HTTP development
• Dapr HTTP cron Handler in Go - Template project to jump start your Dapr service development for scheduled workloads

Contributing to Dapr Go client

See the Contribution Guide to get started with building and developing.

Documentation

Index

• Constants
• func NewService(address string) common.Service
• func NewServiceWithMux(address string, mux *chi.Mux) common.Service
• type Server
  • func (s *Server) AddBindingInvocationHandler(route string, fn common.BindingInvocationHandler) error
  • func (s *Server) AddHealthCheckHandler(route string, fn common.HealthCheckHandler) error
  • func (s *Server) AddJobEventHandler(name string, fn common.JobEventHandler) error
  • func (s *Server) AddServiceInvocationHandler(route string, fn common.ServiceInvocationHandler) error
  • func (s *Server) AddTopicEventHandler(sub *common.Subscription, fn common.TopicEventHandler) error
  • func (s *Server) GracefulStop() error
  • func (s *Server) RegisterActorImplFactory(f actor.Factory, opts ...config.Option)
  • func (s *Server) RegisterActorImplFactoryContext(f actor.FactoryContext, opts ...config.Option)
  • func (s *Server) Start() error
  • func (s *Server) Stop() error

Constants

const (
	// PubSubHandlerSuccessStatusCode is the successful ack code for pubsub event appcallback response.
	PubSubHandlerSuccessStatusCode int = http.StatusOK

	// PubSubHandlerRetryStatusCode is the error response code (nack) pubsub event appcallback response.
	PubSubHandlerRetryStatusCode int = http.StatusInternalServerError

	// PubSubHandlerDropStatusCode is the pubsub event appcallback response code indicating that Dapr should drop that message.
	PubSubHandlerDropStatusCode int = http.StatusSeeOther

	// HealthzRoute Health check default route used by the server
	HealthzRoute = "healthz"
)

Functions

func NewService

func NewService(address string) common.Service

NewService creates new Service.

func NewServiceWithMux

func NewServiceWithMux(address string, mux *chi.Mux) common.Service

NewServiceWithMux creates new Service with existing http mux.

Types

type Server

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

Server is the HTTP server wrapping mux many Dapr helpers.

func (*Server) AddBindingInvocationHandler

func (s *Server) AddBindingInvocationHandler(route string, fn common.BindingInvocationHandler) error

AddBindingInvocationHandler appends provided binding invocation handler with its route to the service.

func (*Server) AddHealthCheckHandler

func (s *Server) AddHealthCheckHandler(route string, fn common.HealthCheckHandler) error

AddHealthCheckHandler appends provided app health check handler.

func (*Server) AddJobEventHandler

func (s *Server) AddJobEventHandler(name string, fn common.JobEventHandler) error

func (*Server) AddServiceInvocationHandler

func (s *Server) AddServiceInvocationHandler(route string, fn common.ServiceInvocationHandler) error

AddServiceInvocationHandler appends provided service invocation handler with its route to the service.

func (*Server) AddTopicEventHandler

func (s *Server) AddTopicEventHandler(sub *common.Subscription, fn common.TopicEventHandler) error

AddTopicEventHandler appends provided event handler with it's name to the service.

func (*Server) GracefulStop

func (s *Server) GracefulStop() error

func (*Server) RegisterActorImplFactory

func (s *Server) RegisterActorImplFactory(f actor.Factory, opts ...config.Option)

Deprecated: Use RegisterActorImplFactoryContext instead.

func (*Server) RegisterActorImplFactoryContext

func (s *Server) RegisterActorImplFactoryContext(f actor.FactoryContext, opts ...config.Option)

func (*Server) Start

func (s *Server) Start() error

Start starts the HTTP handler. Blocks while serving.

func (*Server) Stop

func (s *Server) Stop() error

Stop stops previously started HTTP service with a five second timeout.