humacli

Documentation

Index

• func WithOptions[Options any](f func(cmd *cobra.Command, args []string, options *Options)) func(*cobra.Command, []string)
• type CLI
  • func New[O any](onParsed func(Hooks, *O)) CLI
• type Hooks

Examples

• CLI

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
	mux := http.NewServeMux()
	api := humago.New(mux, 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: mux,
		// 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()

func New

func New[O any](onParsed func(Hooks, *O)) CLI

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.