http

README

Things-Kit HTTP

HTTP Server Interface for Things-Kit

This module defines the HTTP server abstraction for Things-Kit applications. It contains only interfaces, no implementation.

Installation

go get github.com/things-kit/things-kit-http

Purpose

The things-kit-http package defines the contract that all HTTP server implementations must follow. This allows applications to program against a stable interface while being free to choose any HTTP framework (Gin, Echo, Chi, stdlib, etc.).

Interface

type Server interface {
    // GetEngine returns the underlying HTTP router/engine for advanced usage
    GetEngine() any
    
    // RegisterHandler registers a handler function with the given HTTP method and path
    RegisterHandler(method, path string, handler any)
}

Available Implementations

things-kit-httpgin (Recommended)

The things-kit-httpgin module provides a Gin-based implementation.

import (
    "github.com/things-kit/things-kit/app"
    "github.com/things-kit/things-kit-httpgin"
)

func main() {
    app.New(
        viperconfig.Module,
        logging.Module,
        httpgin.Module,  // Provides http.Server
        
        fx.Invoke(RegisterRoutes),
    ).Run()
}

Creating Your Own Implementation

You can create custom HTTP server implementations using any framework:

package myhttp

import "github.com/things-kit/things-kit-http"

type MyHTTPServer struct {
    engine *YourFramework
}

func (s *MyHTTPServer) GetEngine() any {
    return s.engine
}

func (s *MyHTTPServer) RegisterHandler(method, path string, handler any) {
    // Register handler with your framework
}

License

MIT License - see LICENSE file for details

Documentation

Overview

Package http defines framework-level HTTP server abstractions. This package provides interfaces that HTTP implementations must satisfy, allowing users to swap HTTP frameworks (Gin, Chi, Echo, stdlib, etc.) while maintaining compatibility with the framework.

For a production-ready implementation, see the httpgin package.

Index

• type Config
• type Handler
• type Server

Types

type Config

type Config struct {
	Port int    `mapstructure:"port"` // Port to listen on
	Host string `mapstructure:"host"` // Host to bind to (empty = all interfaces)
}

Config holds common HTTP server configuration. Specific implementations may embed this struct and add framework-specific fields.

type Handler

type Handler interface {
	// RegisterRoutes registers this handler's routes with the HTTP router.
	// The router parameter should be cast to the appropriate type by the implementation.
	RegisterRoutes(router any)
}

Handler represents a component that can register HTTP routes. The router parameter type depends on the HTTP implementation being used. For example, *gin.Engine for Gin, chi.Router for Chi, etc.

type Server

type Server interface {
	// Start begins listening for HTTP requests.
	// This should be non-blocking and return immediately after the server starts.
	// The implementation should start a goroutine for the actual serving.
	Start(ctx context.Context) error

	// Stop gracefully shuts down the HTTP server.
	// It should wait for in-flight requests to complete within the context deadline.
	// Implementations should respect the context's cancellation/timeout.
	Stop(ctx context.Context) error

	// Addr returns the address the server is listening on (e.g., ":8080").
	Addr() string
}

Server represents an HTTP server that can be started and stopped. Implementations should handle the lifecycle of the HTTP server including graceful shutdown and proper error handling.