EiluneKit

module
v0.4.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 17, 2026 License: MIT

README

EiluneKit

Resources: 中文.

EiluneKit is a small Go toolkit for auth, HTTP services, Postgres, Redis, logging, and narrow runtime helpers. Import the packages you need; there is no central framework.

Installation

go get github.com/Ithildur/EiluneKit@latest

Requires Go 1.27.1 or newer.

Design

  • auth owns shared principal helpers and transport-neutral auth flows. auth/http adapts the default session auth flow to HTTP; auth/rbac and auth/rbac/http handle multi-user JSON bearer auth.
  • http/routes keeps route metadata next to handlers. Route is the data model; Blueprint is the recommended builder. NewHandler builds a complete HTTP handler with application-supplied middleware and failure responses.
  • Built-in auth is optional. Applications can use their own middleware, principals, sessions, and login routes; see application authentication.
  • tools/openapi optionally turns final route metadata into validated OpenAPI 3.1 JSON. Handlers remain ordinary net/http handlers without runtime schema validation.
  • http/static mounts static files and SPA handlers from project-relative paths such as dist or web/dist.
  • postgres/migration runs explicit Goose-backed Postgres migrations with session advisory locking and startup checks for pending or newer schemas.

Usage

Minimal single-process auth setup without Redis or Postgres:

store := authstore.NewMemoryStore()

manager, err := authjwt.New(signingKey, store)
if err != nil {
	return err
}

login, err := authhttp.NewStaticPassword("dashboard-admin", adminPassword)
if err != nil {
	return err
}

authHandler, err := authhttp.NewHandler(manager, authhttp.Options{
	LoginAuthenticator: login,
})
if err != nil {
	return err
}

if err := authHandler.Register(r); err != nil {
	return err
}

Static password auth ignores the request username and returns the configured user ID when the password matches. POST /auth/login still requires persistence with session or persistent.

This uses in-process session storage for one process; sessions are not shared across instances and do not survive process restarts.

Start with the package docs:

  • http/routes/README.md: route declarations, Blueprint, NewHandler, and lower-level Route/Mount
  • http/middleware/README.md: request IDs, recovery, CORS, compression, access logging, and limits
  • http/response/README.md: JSON error presets, overrides, and custom business handlers
  • auth/http/README.md: single-user cookie auth endpoints and bearer middleware for chi
  • auth/rbac/http/README.md: multi-user JSON bearer auth endpoints and role/scope middleware
  • postgres/README.md: GORM and pgx connection helpers, plus explicit schema migrations
  • redis/README.md: Redis client setup and TLS option

Package Layout

  • auth: shared principal helpers, transport-neutral auth service, credential interfaces, static password helpers, and login lockout primitives
  • auth/rbac: multi-user auth service, principal loading, role policy, lockout, API token, and audit hook contracts
  • auth/http: default session auth handlers, bearer middleware, login rate limiting, optional login lockout, and session revocation endpoints
  • auth/rbac/http: JSON bearer auth handlers and RBAC middleware
  • auth/jwt: access and refresh JWT issuance backed by auth/store
  • auth/session: cookie and CSRF helpers
  • auth/store: session and token state interfaces and memory store
  • auth/store/redissession: Redis-backed auth session store
  • http/decoder: JSON request decoding helpers
  • http/middleware: request IDs, recovery, CORS, compression, JSON-only guards, access logging, and limits
  • http/response: JSON writers and optional error handlers
  • http/routes: declarative routes, request and response contracts, and runtime mounting
  • http/static: static file and SPA mounting helpers
  • postgres/dbtypes: thin database type aliases
  • postgres/gorm: Postgres DSN and *gorm.DB helpers
  • postgres/migration: Goose-backed Postgres migration execution and schema-version checks
  • postgres/pgx: Postgres DSN and *pgxpool.Pool helpers
  • redis: Redis client helpers
  • logging: slog-based logging helpers
  • appdir: application home directory discovery
  • contextutil: context and timeout helpers
  • clientip: client IP extraction helpers
  • tools/openapi: optional OpenAPI 3.1 generation and validation

Documentation

  • auth/rbac/README.md
  • auth/rbac/README_CN.md
  • auth/http/README.md
  • auth/http/README_CN.md
  • auth/rbac/http/README.md
  • auth/rbac/http/README_CN.md
  • http/routes/README.md
  • http/routes/README_CN.md
  • http/middleware/README.md
  • http/middleware/README_CN.md
  • http/response/README.md
  • http/response/README_CN.md
  • postgres/README.md
  • postgres/README_CN.md
  • redis/README.md
  • redis/README_CN.md
  • SECURITY.md
  • SECURITY_CN.md

Development

Run tests from the repository root:

go test ./...

License

MIT. See LICENSE.

Directories

Path Synopsis
Package appdir discovers the application home directory.
 Package appdir discovers the application home directory.
Package auth provides transport-neutral authentication flows.
 Package auth provides transport-neutral authentication flows.
http
jwt
Package jwt provides JWT issuance and validation backed by user/session state.
 Package jwt provides JWT issuance and validation backed by user/session state.
rbac
Package rbac provides role and scope based authentication primitives.
 Package rbac provides role and scope based authentication primitives.
rbac/http
session
Package session provides cookie helpers for auth flows.
 Package session provides cookie helpers for auth flows.
store
Package store defines auth session persistence used by auth/jwt.
 Package store defines auth session persistence used by auth/jwt.
store/redissession
Package redissession provides Redis-backed auth session storage.
 Package redissession provides Redis-backed auth session storage.
Package clientip provides client IP helpers.
 Package clientip provides client IP helpers.
Package contextutil provides context helpers.
 Package contextutil provides context helpers.
http
decoder
middleware
Package middleware provides reusable HTTP middleware.
 Package middleware provides reusable HTTP middleware.
response
Package response provides JSON response helpers.
 Package response provides JSON response helpers.
routes
Package routes provides declarative route definitions and middleware composition.
 Package routes provides declarative route definitions and middleware composition.
static
Package static provides static file and SPA helpers.
 Package static provides static file and SPA helpers.
internal
routepath
Package routepath defines endpoint paths and route prefixes.
 Package routepath defines endpoint paths and route prefixes.
Package logging provides slog-based logging.
 Package logging provides slog-based logging.
postgres
dbtypes
Package dbtypes provides database type aliases to keep pq out of business imports.
 Package dbtypes provides database type aliases to keep pq out of business imports.
gorm
Package gorm provides GORM helpers for Postgres.
 Package gorm provides GORM helpers for Postgres.
internal/dsn
Package dsn builds Postgres DSNs.
 Package dsn builds Postgres DSNs.
migration
Package migration provides Goose-backed PostgreSQL schema migration helpers.
 Package migration provides Goose-backed PostgreSQL schema migration helpers.
pgx
Package pgx provides pgx pool helpers for Postgres.
 Package pgx provides pgx pool helpers for Postgres.
Package redis provides Redis client helpers.
 Package redis provides Redis client helpers.
tools
openapi
Package openapi generates and validates OpenAPI 3.1 JSON from routes metadata.
 Package openapi generates and validates OpenAPI 3.1 JSON from routes metadata.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.