diff --git a/e5e.go b/e5e.go index c711a87..39212fa 100644 --- a/e5e.go +++ b/e5e.go @@ -86,7 +86,7 @@ type Request[T, TContext Data] struct { Event Event[T] `json:"event"` } -// Data provides a shortcut to [r.Event.Data]. +// Data provides a shortcut to the Data of the inner [Event]. func (r Request[T, TContext]) Data() T { return r.Event.Data } // Result represents the function result value passed back to E5E. diff --git a/errors.go b/errors.go index e51fe35..2a0dd3e 100644 --- a/errors.go +++ b/errors.go @@ -2,7 +2,7 @@ package e5e import "fmt" -// InvalidEntrypointError is returned if the given entrypoint did not get registered on runtime. +// InvalidEntrypointError is returned if the given entrypoint did not get registered before invoking [Start]. type InvalidEntrypointError struct{ Entrypoint string } func (e InvalidEntrypointError) Error() string { diff --git a/handler.go b/handler.go index 9cf9263..35c41ae 100644 --- a/handler.go +++ b/handler.go @@ -8,7 +8,7 @@ import ( // A Handler responds to a request. // -// [Handle] should write reply headers and data to the given result and then return. +// Handle should write the response data with optional metadata to the given result. // Returning signals that the request is finished. // // Except for reading the body, handlers should not modify the provided [Event]. @@ -24,9 +24,9 @@ type Handler[T, TContext Data] interface { // HandlerFactory provides an interface to a struct that wraps a job to be done // combined with a function that can execute it. Its main purpose is to -// wrap a struct that contains generic types (like a Worker[T] that needs to be -// invoked with a Request[T]) in such a way as to make it non-generic so that it can -// be used in other non-generic code like [mux]. +// wrap a struct that contains generic types (like a Handler[T, TContext] that needs to be +// invoked with a Request[T, TContext]) in such a way as to make it non-generic so that it can +// be used in other non-generic code like the global mux. type HandlerFactory interface { // Execute the handler with payload, which should be a deserializable JSON object. // Any errors that occur due to deserialization or otherwise are returned. @@ -59,5 +59,5 @@ func createHandlerFunc[T, TContext Data](f func(context.Context, Request[T, TCon } // Handlers returns all registered handlers. -// It should not be modified directly, instead add new handlers only via [AddHandler] or [addHandlerSafely]. +// It should not be modified directly, instead add new handlers only via [AddHandlerFunc]. func Handlers() map[string]HandlerFactory { return globalMux.handlers } diff --git a/mux.go b/mux.go index 61c6c38..afc04eb 100644 --- a/mux.go +++ b/mux.go @@ -32,10 +32,12 @@ func init() { // Start starts the global mux. // -// The runtime arguments are read from os.Args and based on that, -// the entrypoint which was added via [AddHandlerFunc] before that gets called. +// On startup, the runtime arguments are read from [os.Args]. +// This determines the entrypoint to be used for incoming E5E calls. +// Therefore, the developer must ensure, that a respective handler is registered using [AddHandlerFunc] +// before this function is called. // -// Every error that is happening will cause a panic. +// All runtime errors panic. func Start(ctx context.Context) { args, err := parseArguments(os.Args) if err != nil { @@ -50,6 +52,8 @@ func Start(ctx context.Context) { // AddHandlerFunc adds the handler for the given entrypoint to the global handler. // It panics if the entrypoint was already registered. +// +// Already registered handlers can be queried by calling [Handlers]. func AddHandlerFunc[T, TContext Data](entrypoint string, fn func(context.Context, Request[T, TContext]) (*Result, error)) { if err := addHandlerSafely(globalMux, entrypoint, createHandlerFunc[T, TContext](fn)); err != nil { panic(err) @@ -109,11 +113,6 @@ func parseArguments(args []string) (options, error) { // // If [options.KeepAlive] is true, the goroutine is blocked and can be cancelled // via the context. It also listens for incoming [syscall.SIGINT] signals and stops gracefully. -// -// # Example usage -// -// mux := e5e.NewMux() -// log.Fatalf("mux error: %v", mux.Start(context.Background())) func (m *mux) Start(ctx context.Context, opts options) error { if _, hasEntrypoint := m.handlers[opts.Entrypoint]; !hasEntrypoint { return InvalidEntrypointError{opts.Entrypoint}