Documentation
¶
Overview ¶
Example (ComponentLazyInit) ¶
This example demonstrates how to use kod.LazyInit to defer component initialization until it is needed.
package main import ( "context" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorldLazy.Get().SayHello(ctx) app.HelloWorld.Get().SayHello(ctx) return nil }) }
Output: helloWorld init lazyHelloWorld init Hello, Lazy! Hello, World! lazyHelloWorld shutdown helloWorld shutdown
Example (ComponentMock) ¶
This example demonstrates how to use kod.WithFakes and kod.Fake to provide a mock implementation of a component.
package main import ( "context" "fmt" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" "go.uber.org/mock/gomock" ) func main() { mock := helloworld.NewMockHelloWorld(gomock.NewController(nil)) mock.EXPECT().SayHello(gomock.Any()).Return() kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorld.Get().SayHello(ctx) fmt.Println("Nothing printed from mock") return nil }, kod.WithFakes(kod.Fake[helloworld.HelloWorld](mock))) }
Output: Nothing printed from mock
Example (ComponentRefAndCall) ¶
This example demonstrates how to use kod.Ref to reference a component and call a method on it.
package main import ( "context" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorld.Get().SayHello(ctx) return nil }) }
Output: helloWorld init Hello, World! helloWorld shutdown
Example (ComponentRun) ¶
This example demonstrates how to use kod.Run and kod.Implements to run a simple application.
package main import ( "context" "fmt" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { fmt.Println("Hello, World!") return nil }) }
Output: helloWorld init Hello, World! helloWorld shutdown
Example (ComponentRunMust) ¶
This example demonstrates how to use kod.MustRun and kod.Implements to run a simple application.
package main import ( "context" "fmt" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.MustRun(context.Background(), func(ctx context.Context, app *helloworld.App) error { fmt.Println("Hello, World!") return nil }) }
Output: helloWorld init Hello, World! helloWorld shutdown
Example (ConfigGlobal) ¶
This example demonstrates how to use kod.WithGlobalConfig to provide a global configuration to the application.
package main import ( "context" "fmt" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { fmt.Println(app.Config().Name) return nil }, kod.WithConfigFile("./examples/helloworld/config.toml")) }
Output: helloWorld init globalConfig helloWorld shutdown
Example (ConfigInComponent) ¶
This example demonstrates how to use kod.WithConfig to provide a configuration to the application.
package main import ( "context" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorld.Get().SayHello(ctx) return nil }, kod.WithConfigFile("./examples/helloworld/config.toml")) }
Output: helloWorld init Hello, World!config helloWorld shutdown
Example (InterceptorBuiltin) ¶
This example demonstrates how to use built-in interceptors with kod.WithInterceptors. Such as [krecovery.Interceptor], [ktrace.Interceptor], and [kmetric.Interceptor] ...
package main import ( "context" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" "github.com/go-kod/kod/interceptor/kmetric" "github.com/go-kod/kod/interceptor/krecovery" "github.com/go-kod/kod/interceptor/ktrace" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorld.Get().SayHello(ctx) return nil }, kod.WithInterceptors(krecovery.Interceptor(), ktrace.Interceptor(), kmetric.Interceptor())) }
Output: helloWorld init Hello, World! helloWorld shutdown
Example (InterceptorComponent) ¶
This example demonstrates how to use kod.WithInterceptors to provide component-specific interceptors to the application.
package main import ( "context" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorldInterceptor.Get().SayHello(ctx) return nil }) }
Output: helloWorld init Before call Hello, Interceptor! After call helloWorld shutdown
Example (InterceptorGlobal) ¶
This example demonstrates how to use kod.WithInterceptors to provide global interceptors to the application.
package main import ( "context" "fmt" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" "github.com/go-kod/kod/interceptor" ) func main() { interceptor := interceptor.Interceptor(func(ctx context.Context, info interceptor.CallInfo, req, res []interface{}, next interceptor.HandleFunc) error { fmt.Println("Before call") err := next(ctx, info, req, res) fmt.Println("After call") return err }) kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { app.HelloWorld.Get().SayHello(ctx) return nil }, kod.WithInterceptors(interceptor)) }
Output: helloWorld init Before call Hello, World! After call helloWorld shutdown
Example (OpenTelemetryLog) ¶
This example demonstrates how to use logging with OpenTelemetry.
package main import ( "context" "fmt" "testing" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { logger, observer := kod.NewTestLogger() kod.RunTest(&testing.T{}, func(ctx context.Context, app *helloworld.App) { app.L(ctx).Debug("Hello, World!") app.L(ctx).Info("Hello, World!") app.L(ctx).Warn("Hello, World!") app.L(ctx).Error("Hello, World!") app.HelloWorld.Get().SayHello(ctx) }, kod.WithLogger(logger)) fmt.Println(observer.RemoveKeys("trace_id", "span_id", "time")) }
Output: helloWorld init Hello, World! helloWorld shutdown {"component":"github.com/go-kod/kod/Main","level":"INFO","msg":"Hello, World!"} {"component":"github.com/go-kod/kod/Main","level":"WARN","msg":"Hello, World!"} {"component":"github.com/go-kod/kod/Main","level":"ERROR","msg":"Hello, World!"} {"component":"github.com/go-kod/kod/examples/helloworld/HelloWorld","level":"INFO","msg":"Hello, World!"}
Example (OpenTelemetryMetric) ¶
This example demonstrates how to use metrics with OpenTelemetry.
package main import ( "context" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { metric, _ := app.Meter().Int64Counter("example") metric.Add(ctx, 1) return nil }) }
Output: helloWorld init helloWorld shutdown
Example (OpenTelemetryTrace) ¶
This example demonstrates how to use tracing with OpenTelemetry.
package main import ( "context" "fmt" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" "github.com/go-kod/kod/interceptor/ktrace" ) func main() { logger, observer := kod.NewTestLogger() kod.Run(context.Background(), func(ctx context.Context, app *helloworld.App) error { ctx, span := app.Tracer().Start(ctx, "example") defer span.End() app.L(ctx).Info("Hello, World!") app.L(ctx).WarnContext(ctx, "Hello, World!") app.HelloWorld.Get().SayHello(ctx) return nil }, kod.WithInterceptors(ktrace.Interceptor()), kod.WithLogger(logger)) fmt.Println(observer.Filter(func(m map[string]any) bool { return m["trace_id"] != nil && m["span_id"] != nil }).RemoveKeys("trace_id", "span_id", "time")) }
Output: helloWorld init Hello, World! helloWorld shutdown {"component":"github.com/go-kod/kod/Main","level":"INFO","msg":"Hello, World!"} {"component":"github.com/go-kod/kod/Main","level":"WARN","msg":"Hello, World!"} {"component":"github.com/go-kod/kod/examples/helloworld/HelloWorld","level":"INFO","msg":"Hello, World!"}
Example (TestRun) ¶
This example demonstrates how to use kod.RunTest to run a test function.
package main import ( "context" "testing" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.RunTest(&testing.T{}, func(ctx context.Context, app *helloworld.App) { app.HelloWorld.Get().SayHello(ctx) }) }
Output: helloWorld init Hello, World! helloWorld shutdown
Example (TestWithConfig) ¶
This example demonstrates how to use kod.RunTest and kod.WithConfigFile to run a test function with a configuration.
package main import ( "context" "fmt" "testing" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { kod.RunTest(&testing.T{}, func(ctx context.Context, app *helloworld.App) { fmt.Println(app.Config().Name) app.HelloWorld.Get().SayHello(ctx) }, kod.WithConfigFile("./examples/helloworld/config.toml")) }
Output: helloWorld init globalConfig Hello, World!config helloWorld shutdown
Example (TestWithLogObserver) ¶
This example demonstrates how to use kod.RunTest, kod.NewTestLogger and kod.WithLogger to run a test function with a custom logger.
package main import ( "context" "fmt" "testing" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" ) func main() { logger, observer := kod.NewTestLogger() t := &testing.T{} kod.RunTest(t, func(ctx context.Context, app *helloworld.App) { app.L(ctx).Debug("Hello, World!") app.L(ctx).Info("Hello, World!") app.L(ctx).Warn("Hello, World!") app.L(ctx).Error("Hello, World!") }, kod.WithLogger(logger)) fmt.Println(observer.Len()) fmt.Println(observer.ErrorCount()) fmt.Println(observer.Clean().Len()) }
Output: helloWorld init helloWorld shutdown 3 1 0
Example (TestWithMockComponent) ¶
This example demonstrates how to use kod.RunTest, kod.Fake and kod.WithFakes to run a test function with a mock component.
package main import ( "context" "fmt" "testing" "github.com/go-kod/kod" "github.com/go-kod/kod/examples/helloworld" "go.uber.org/mock/gomock" ) func main() { mock := helloworld.NewMockHelloWorld(gomock.NewController(nil)) mock.EXPECT().SayHello(gomock.Any()).Return() kod.RunTest(&testing.T{}, func(ctx context.Context, app *helloworld.App) { app.HelloWorld.Get().SayHello(ctx) fmt.Println("Nothing printed from mock") }, kod.WithFakes(kod.Fake[helloworld.HelloWorld](mock))) }
Output: Nothing printed from mock
Index ¶
- Constants
- Variables
- func Fake[T any](impl any) fakeComponent
- func MustRun[T any, P PointerToMain[T]](ctx context.Context, run func(context.Context, *T) error, ...)
- func Run[T any, _ PointerToMain[T]](ctx context.Context, run func(context.Context, *T) error, ...) error
- func RunTest[T any](tb testing.TB, body func(context.Context, T), opts ...func(*options))
- func RunTest2[T1, T2 any](tb testing.TB, body func(context.Context, T1, T2), opts ...func(*options))
- func RunTest3[T1, T2, T3 any](tb testing.TB, body func(context.Context, T1, T2, T3), opts ...func(*options))
- func WithConfigFile(filename string) func(*options)
- func WithFakes(fakes ...fakeComponent) func(*options)
- func WithInterceptors(interceptors ...interceptor.Interceptor) func(*options)
- func WithLogger(logger *slog.Logger) func(*options)
- func WithOpenTelemetryDisabled() func(*options)
- func WithRegistrations(regs ...*Registration) func(*options)
- type Implements
- type InstanceOf
- type Kod
- type LazyInit
- type LocalStubFnInfo
- type Main
- type PointerToMain
- type Ref
- type Registration
- type WithConfig
- type WithGlobalConfig
Examples ¶
- Package (ComponentLazyInit)
- Package (ComponentMock)
- Package (ComponentRefAndCall)
- Package (ComponentRun)
- Package (ComponentRunMust)
- Package (ConfigGlobal)
- Package (ConfigInComponent)
- Package (InterceptorBuiltin)
- Package (InterceptorComponent)
- Package (InterceptorGlobal)
- Package (OpenTelemetryLog)
- Package (OpenTelemetryMetric)
- Package (OpenTelemetryTrace)
- Package (TestRun)
- Package (TestWithConfig)
- Package (TestWithLogObserver)
- Package (TestWithMockComponent)
Constants ¶
const (
PkgPath = "github.com/go-kod/kod"
)
Variables ¶
var NewTestLogger = kslog.NewTestLogger
NewTestLogger returns a new test logger.
var Register = registry.Register
Register registers the given component implementations.
Functions ¶
func MustRun ¶ added in v0.14.3
func MustRun[T any, P PointerToMain[T]](ctx context.Context, run func(context.Context, *T) error, opts ...func(*options))
MustRun is a helper function to run the application with the provided main component and options. It panics if an error occurs during the execution.
func Run ¶
func Run[T any, _ PointerToMain[T]](ctx context.Context, run func(context.Context, *T) error, opts ...func(*options)) error
Run initializes and runs the application with the provided main component and options.
func RunTest2 ¶ added in v0.7.0
func RunTest2[T1, T2 any](tb testing.TB, body func(context.Context, T1, T2), opts ...func(*options))
RunTest2 runs a test function with two components.
func RunTest3 ¶ added in v0.7.0
func RunTest3[T1, T2, T3 any](tb testing.TB, body func(context.Context, T1, T2, T3), opts ...func(*options))
RunTest3 runs a test function with three components.
func WithConfigFile ¶
func WithConfigFile(filename string) func(*options)
WithConfigFile is an option setter for specifying a configuration file.
func WithFakes ¶
func WithFakes(fakes ...fakeComponent) func(*options)
WithFakes is an option setter for specifying fake components for testing.
func WithInterceptors ¶ added in v0.6.0
func WithInterceptors(interceptors ...interceptor.Interceptor) func(*options)
WithInterceptors is an option setter for specifying interceptors.
func WithLogger ¶ added in v0.14.2
WithLogger is an option setter for specifying a slog logger.
func WithOpenTelemetryDisabled ¶ added in v0.9.1
func WithOpenTelemetryDisabled() func(*options)
WithOpenTelemetryDisabled is an option setter for disabling OpenTelemetry.
func WithRegistrations ¶
func WithRegistrations(regs ...*Registration) func(*options)
WithRegistrations is an option setter for specifying component registrations.
Types ¶
type Implements ¶
type Implements[T any] struct { // contains filtered or unexported fields }
Implements[T any] provides a common structure for components, with logging/tracing/metrics capabilities and a reference to the component's interface.
func (*Implements[T]) L ¶
func (i *Implements[T]) L(ctx context.Context) *slog.Logger
L returns the associated logger.
func (*Implements[T]) Meter ¶ added in v0.14.3
func (i *Implements[T]) Meter(opts ...metric.MeterOption) metric.Meter
Meter return the associated meter.
func (*Implements[T]) Tracer ¶ added in v0.14.3
func (i *Implements[T]) Tracer(opts ...trace.TracerOption) trace.Tracer
Tracer return the associated tracer.
type InstanceOf ¶
type InstanceOf[T any] interface { // contains filtered or unexported methods }
InstanceOf[T any] is an interface for asserting implementation of an interface T.
type Kod ¶
type Kod struct {
// contains filtered or unexported fields
}
Kod represents the core structure of the application, holding configuration and component registrations.
func FromContext ¶
FromContext returns the Kod value stored in ctx, if any.
type LazyInit ¶ added in v0.10.0
type LazyInit struct{}
LazyInit is a marker type for lazy initialization of components.
type LocalStubFnInfo ¶
type LocalStubFnInfo = registry.LocalStubFnInfo
LocalStubFnInfo is the information passed to LocalStubFn.
type Main ¶
type Main interface{}
Main is the interface that should be implemented by an application's main component. The main component is the entry point of the application, and is expected to be a struct that embeds Implements[Main].
Example:
type app struct { kod.Implements[kod.Main] } func main() { kod.Run(context.Background(), func(ctx context.Context, main *app) error { fmt.Println("Hello, World!") return nil }) }
type PointerToMain ¶
type PointerToMain[T any] interface { *T InstanceOf[Main] }
PointerToMain is a type constraint that asserts *T is an instance of Main (i.e. T is a struct that embeds kod.Implements[kod.Main]).
type Ref ¶
type Ref[T any] struct { // contains filtered or unexported fields }
Ref[T any] is a reference holder to a value of type T. The reference is expected to be a field of a component struct. The value is set by the framework, and is accessible via the Get() method.
Example:
type app struct { kod.Implements[kod.Main] component kod.Ref[example.Component] } func main() { kod.Run(context.Background(), func(ctx context.Context, main *app) error { component := main.component.Get() // ... }) }
type Registration ¶
type Registration = registry.Registration
Registration is the registration information for a component.
type WithConfig ¶
type WithConfig[T any] struct { // contains filtered or unexported fields }
WithConfig[T any] is a struct to hold configuration of type T. The struct is expected to be a field of a component struct. The configuration is loaded from a file, and is accessible via the Config() method.
Example:
type app struct { kod.Implements[kod.Main] kod.WithConfig[appConfig] } type appConfig struct { Host string Port int } func main() { kod.Run(context.Background(), func(ctx context.Context, main *app) error { fmt.Println("config:", main.Config()) }) }
func (*WithConfig[T]) Config ¶
func (wc *WithConfig[T]) Config() *T
Config returns a pointer to the config.
type WithGlobalConfig ¶ added in v0.12.0
type WithGlobalConfig[T any] struct { // contains filtered or unexported fields }
WithGlobalConfig[T any] is a struct to hold global configuration of type T. The struct is expected to be a field of a component struct. The configuration is loaded from a file, and is accessible via the Config() method.
func (*WithGlobalConfig[T]) Config ¶ added in v0.12.0
func (wc *WithGlobalConfig[T]) Config() *T
Config returns a pointer to the config.
Directories
¶
Path | Synopsis |
---|---|
cmd
|
|
kod/internal
Package files contains file-related utilities.
|
Package files contains file-related utilities. |
examples
module
|
|
helloworld
Package helloworld is a generated GoMock package.
|
Package helloworld is a generated GoMock package. |
ext
module
|
|
internal
|
|
tests
module
|