Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithOptions ¶
func WithOptions[Options any](f func(cmd *cobra.Command, args []string, options *Options)) func(*cobra.Command, []string)
WithOptions is a helper for custom commands that need to access the options.
cli.Root().AddCommand(&cobra.Command{
Use: "my-custom-command",
Run: huma.WithOptions(func(cmd *cobra.Command, args []string, opts *Options) {
fmt.Println("Hello " + opts.Name)
}),
})
Types ¶
type CLI ¶
type CLI interface {
// Run the CLI. This will parse the command-line arguments and environment
// variables and then run the appropriate command. If no command is given,
// the default command will call the `OnStart` function to start a server.
Run()
// Root returns the root Cobra command. This can be used to add additional
// commands or flags. Customize it however you like.
Root() *cobra.Command
}
CLI is an optional command-line interface for a Huma service. It is provided as a convenience for quickly building a service with configuration from the environment and/or command-line options, all tied to a simple type-safe Go struct.
Example ¶
// First, define your input options.
type Options struct {
Debug bool `doc:"Enable debug logging"`
Host string `doc:"Hostname to listen on."`
Port int `doc:"Port to listen on." short:"p" default:"8888"`
}
// Then, create the CLI.
cli := humacli.New(func(hooks humacli.Hooks, opts *Options) {
fmt.Printf("Options are debug:%v host:%v port%v\n",
opts.Debug, opts.Host, opts.Port)
// Set up the router & API
router := chi.NewRouter()
api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
huma.Register(api, huma.Operation{
OperationID: "hello",
Method: http.MethodGet,
Path: "/hello",
}, func(ctx context.Context, input *struct{}) (*struct{}, error) {
// TODO: implement handler
return nil, nil
})
srv := &http.Server{
Addr: fmt.Sprintf("%s:%d", opts.Host, opts.Port),
Handler: router,
// TODO: Set up timeouts!
}
hooks.OnStart(func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatalf("listen: %s\n", err)
}
})
hooks.OnStop(func() {
srv.Shutdown(context.Background())
})
})
// Run the thing!
cli.Run()
Output:
func New ¶
New creates a new CLI. The `onParsed` callback is called after the command options have been parsed and the options struct has been populated. You should set up a `hooks.OnStart` callback to start the server with your chosen router.
// First, define your input options.
type Options struct {
Debug bool `doc:"Enable debug logging"`
Host string `doc:"Hostname to listen on."`
Port int `doc:"Port to listen on." short:"p" default:"8888"`
}
// Then, create the CLI.
cli := humacli.CLI(func(hooks humacli.Hooks, opts *Options) {
fmt.Printf("Options are debug:%v host:%v port%v\n",
opts.Debug, opts.Host, opts.Port)
// Set up the router & API
router := chi.NewRouter()
api := humachi.New(router, huma.DefaultConfig("My API", "1.0.0"))
srv := &http.Server{
Addr: fmt.Sprintf("%s:%d", opts.Host, opts.Port),
Handler: router,
// TODO: Set up timeouts!
}
hooks.OnStart(func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatalf("listen: %s\n", err)
}
})
hooks.OnStop(func() {
srv.Shutdown(context.Background())
})
})
// Run the thing!
cli.Run()
type Hooks ¶
type Hooks interface {
// OnStart sets a function to call when the service should be started. This
// is called by the default command if no command is given. The callback
// should take whatever steps are necessary to start the server, such as
// `httpServer.ListenAndServer(...)`.
OnStart(func())
// OnStop sets a function to call when the service should be stopped. This
// is called by the default command if no command is given. The callback
// should take whatever steps are necessary to stop the server, such as
// `httpServer.Shutdown(...)`.
OnStop(func())
}
Hooks is an interface for setting up callbacks for the CLI. It is used to start and stop the service.
Source Files
Click to show internal directories.
Click to hide internal directories.