core

README

AMWK - AntMind WebKit Framework

AMWK is a lightweight, modular web framework designed for simplifying web application development in Go. It provides a highly flexible core with pluggable adapters for different runtimes (net/http, AWS Lambda, etc.).

[!IMPORTANT] This repository is in early development. The core design and APIs are still evolving, and breaking changes may occur. We welcome feedback and contributions to help improve the framework.

Why this design

• Context-first: most common operations (params, binding, response rendering, control flow, shared values) are exposed on core.Context, so users rarely need to use raw *http.Request or low-level response objects.
• Small, stable core: the core package exposes only abstract interfaces (Context, Request, Response, Application, HandlerFunc, Logger). Implementations live in engine, web, lambda, etc.
• Pluggable adapters: same middleware and handlers can run on net/http or AWS Lambda with minimal changes because adapters translate platform requests/responses to the core interfaces.
• Middleware-first: full support for global, group, and request-local middleware (the framework supports ctx.Use(...) to append middleware only for the current request).

---

Framework Modules

• core: The core module defines the fundamental interfaces and types for the framework. It provides the basic building blocks for handling requests and responses in a platform-agnostic way.
• engine: The engine module implements an adapter-agnostic request handling engine. It provides the main request processing loop, middleware chaining, and more.
• web: An HTTP adapter that based on Go's net/http package.
• examples: A collection of runnable examples demonstrating various features and use cases of the framework.

---

Getting Started

The AMWK framework requires Go 1.22 or later.

Install an adapter (e.g. web) and its dependencies:

go get github.com/go-amwk/web
go mod tidy

Create a simple application by the web HTTP adapter to render "Hello, World!" for all requests:

package main

import (
  "github.com/go-amwk/core"
  "github.com/go-amwk/web"
)

func main() {
  app := web.Default()

  app.Use(func(ctx core.Context) error {
    ctx.Write([]byte("hello world"))
    return nil
  })

  app.Start()
}

---

Examples

We provide a set of runnable examples in the examples repo to demonstrate various features and use cases of the framework.

• examples/hello-world: A minimal example showing how to create a simple "Hello, World!" application using the framework and the web adapter.
• examples/query-params: An example demonstrating how to handle query parameters in requests and use them in responses.
• ...

Each example folder should include a README explaining how to run, test, and extend the example.

---

Contributing

We welcome contributions. Suggested process:

1. Open an Issue to discuss large API or core changes (especially any core interface changes).
2. Fork -> feature branch -> PR:
   • Run go test ./... and lints (golangci-lint) locally.
   • Include tests for new functionality.
   • Keep PRs small and focused.
3. API stability:
   • core is a stable contract. Breaking changes should target a new major version and be discussed in an issue first.
4. Tests & CI:
   • Provide unit tests and integration tests for adaptors and engine behavior.
   • Update examples or add new examples when adding features.
5. CLA / licensing:
   • By contributing, you agree to the repository license (see LICENSE).

See CONTRIBUTING.md in the repository root for templates and more details.

---

License

This project uses the MIT License. See LICENSE in the repository root.

Documentation

Index

• type Application
• type Context
• type HandlerFunc
• type HandlersChain
• type Request
• type Response

Types

type Application

type Application interface {
	// Start starts the application server and listens for incoming requests. It returns an error if
	// it fails to start.
	Start() error
	// Use adds the given handlers to the application.
	Use(handlers ...HandlerFunc) Application
	// Close closes the application.
	Close() error
	// Shutdown gracefully shuts down the application server.
	Shutdown(ctx context.Context) error
}

Application is the interface for a web application.

type Context

type Context interface {
	// Get returns the value associated with the key in the context.
	Get(string) (any, bool)
	// Set sets the value for the key in the context and returns the previous value.
	Set(string, any) any
	// Context returns the context.Context associated with the request.
	Context() context.Context

	// Application returns the application instance associated with the context.
	Application() Application

	// Abort marks the context as aborted, and subsequent handlers will not be executed.
	Abort()
	// IsAbort checks if the context is marked as aborted.
	IsAbort() bool
	// Next calls the next handler in the handlers chain.
	Next() error
	// Use adds handlers to the context, which will be executed in the order they are added.
	Use(...HandlerFunc)

	// Body returns the request body as a readable stream.
	Body() (io.ReadCloser, error)
	// ClientIP returns the IP address of the client making the request.
	ClientIP() string
	// ContentLength returns the length of the request body in bytes.
	ContentLength() int64
	// ContentType returns the Content-Type header of the request.
	ContentType() string
	// Cookie retrieves a cookie by name from the request.
	Cookie(string) (*http.Cookie, error)
	// Cookies returns all cookies from the request.
	Cookies() []*http.Cookie
	// Header retrieves a header value by name from the request.
	Header(string) string
	// HeaderValues retrieves all values for a header by name from the request.
	HeaderValues(string) []string
	// Headers returns all headers from the request.
	Headers() http.Header
	// Method returns the HTTP method of the request (e.g., GET, POST).
	Method() string
	// Protocol returns the HTTP protocol version of the request (e.g., HTTP/1.1).
	Protocol() string
	// Path returns the request path.
	Path() string
	// PathValue retrieves a path parameter value by name from the request.
	PathValue(string) string
	// Resource returns the resource pattern of the request.
	Resource() string
	// Query retrieves a query parameter value by name from the request.
	Query(string) string
	// QueryValues retrieves all values for a query parameter by name from the request.
	QueryValues(string) []string
	// Queries returns all query parameters from the request as a url.Values.
	Queries() url.Values

	// AddHeader adds a header to the response.
	AddHeader(string, string)
	// SetHeader sets a header in the response.
	SetHeader(string, string)
	// GetHeader retrieves a header value by name from the response.
	GetHeader(string) string
	// DelHeader deletes a header from the response.
	DelHeader(string)
	// Status sets the HTTP status code for the response and returns an error if it fails.
	Status(int) error
	// Write writes data to the response body.
	Write([]byte) (int, error)

	// Request returns the wrapped Request object associated with the context.
	Request() Request
	// Response returns the wrapped Response object associated with the context.
	Response() Response
}

Context is the interface that represents the context of a single HTTP request.

type HandlerFunc

type HandlerFunc func(Context) error

HandlerFunc defines a function to serve HTTP requests.

type HandlersChain

type HandlersChain []HandlerFunc

HandlersChain defines a slice of HandlerFunc.

type Request

type Request interface {
	// Body returns the request body as a readable stream.
	Body() (io.ReadCloser, error)
	// ClientIP returns the IP address of the client making the request.
	ClientIP() string
	// ContentLength returns the length of the request body in bytes.
	ContentLength() int64
	// Cookie retrieves a cookie by name from the request.
	Cookie(string) (*http.Cookie, error)
	// Cookies returns all cookies from the request.
	Cookies() []*http.Cookie
	// Context returns the context.Context associated with the request.
	Context() context.Context
	// Header retrieves a header value by name from the request.
	Header(string) string
	// HeaderValues retrieves all values for a header by name from the request.
	HeaderValues(string) []string
	// Headers returns all headers from the request.
	Headers() http.Header
	// Method returns the HTTP method of the request (e.g., GET, POST).
	Method() string
	// Protocol returns the HTTP protocol version of the request (e.g., HTTP/1.1).
	Protocol() string
	// Path returns the request path.
	Path() string
	// PathValue retrieves a path parameter value by name from the request.
	PathValue(string) string
	// SetPathValue sets a path parameter value by name in the request.
	SetPathValue(string, string)
	// Resource returns the resource pattern of the request.
	Resource() string
	// SetResource sets the resource pattern of the request.
	SetResource(string)
	// Query retrieves a query parameter value by name from the request.
	Query(string) string
	// QueryValues retrieves all values for a query parameter by name from the request.
	QueryValues(string) []string
	// Queries returns all query parameters from the request as a url.Values.
	Queries() url.Values

	// Request returns the underlying request object, which can be of any type depending on the implementation.
	Request() any
}

Request is the interface that represents an HTTP request.

type Response

type Response interface {
	// AddHeader adds a header value for the response.
	AddHeader(string, string)
	// SetHeader sets a header value for the response.
	SetHeader(string, string)
	// GetHeader retrieves a header value by name from the response.
	GetHeader(string) string
	// DelHeader deletes a header from the response.
	DelHeader(string)
	// Headers returns all headers from the response.
	Headers() http.Header
	// Write writes data to the response body.
	Write([]byte) (int, error)
	// Status sets the HTTP status code for the response.
	Status(int)
	// StatusCode returns the current HTTP status code of the response.
	StatusCode() int

	// Response returns the underlying response object, which can be of any type depending on the implementation.
	Response() any
}

Response is the interface that represents an HTTP response.