requestCore

README

requestCore

Framework-agnostic Go request lifecycle — one handler API across Gin, Fiber, and net/http

Quick Start · Examples · Why · Features · Docs · Contributing · Roadmap

---

requestCore is a Go library for handling RESTful requests with a framework-agnostic core and adapters for Gin, Fiber, and net/http. It provides a unified request/context layer, query execution abstractions, response handling, logging, tracing, and testing utilities.

It is designed to reduce boilerplate around request processing while keeping the implementation composable, interface-driven, and portable across web frameworks.

---

Why requestCore?

The problem

Every backend service repeats the same cross-cutting work on every request: parse the input consistently, log and trace the call, detect duplicates, run the query, and return a uniform error response. Most teams hand-write this once per framework — and pay for it again when they adopt or migrate to a second one. The result is boilerplate that is locked to Gin, Fiber, or chi and can't move.

What requestCore gives you

• One request API across Gin, Fiber, and net/http via webFramework.RequestParser
• Composable handler pipeline — parse, validate, persist, execute, respond (handlers/baseHandler.go)
• Database abstraction — Oracle, PostgreSQL, MySQL, SQLite, MockDB (libQuery/)
• Observability built in — OpenTelemetry, slog, Splunk adapters (libTracing/, libLogger/)
• Incremental adoption — use only the adapter/parser layer, or the full request lifecycle

When to use it

• Teams on multiple HTTP frameworks (or migrating between them)
• Services needing request audit/persistence and duplicate checking
• Projects using sqlc + database/sql or GORM with shared query/error handling
• Platforms standardizing logging and tracing without coupling business logic to Gin/Fiber

When not to use it

• A minimal API where stdlib or a single framework with no shared infra is enough
• Greenfield apps that won't need request persistence, multi-DB, or cross-framework portability

Compared to alternatives

Approach	Strength	requestCore adds
Raw Gin / Fiber / chi	Simple, fast	Unified parsing, lifecycle, DB, observability across frameworks
Middleware-only stack	Lightweight	Request persistence, duplicate detection, query runner, handler orchestration
Rolling your own	Full control	Reusable, tested abstractions already in this repo

---

See it in action

Runnable examples: examples/

• chi + net/http — recommended starting point
• Gin
• Fiber

Each example exposes the same three routes (/health, /users/{id}, /echo) so you can see the same handler code run unchanged across frameworks.

Demo asset (TODO): an architecture diagram or asciinema cast showing the same handler running under chi, Gin, and Fiber would belong here. Not yet produced — contributions welcome (see Contributing).

---

Quick start

Pick a runnable example:

go run ./examples/chi-hello
curl http://localhost:8080/users/42

For the full request lifecycle (DB, persistence, handlers), see examples/README.md and the handlers package.

Installation

go get github.com/hmmftg/requestCore

Then import the package in your project:

import "github.com/hmmftg/requestCore"

---

Features

• Framework adapters

  • Gin
  • Fiber
  • net/http
  • testing support

• Unified request context

  • normalized access to framework context
  • request metadata extraction
  • trace propagation
  • user identity handling

• Query and DB abstraction

  • multi-database support
  • query runner abstraction
  • mock database mode for tests

• Request lifecycle helpers

  • request initialization
  • duplicate request detection
  • request insert/update flows
  • context-aware request operations

• Structured logging

  • slog-based logging support
  • framework-aware logger integrations
  • Splunk-oriented logging support

• OpenTelemetry support

  • trace extraction and propagation
  • request context instrumentation
  • observability-friendly design

• Testing utilities

  • fake/mock infrastructure
  • testing-aware context initialization
  • mock DB mode

• Additional utilities

  • validation helpers
  • response helpers
  • error handling
  • crypto/security helpers
  • HTTP API calling utilities
  • Swagger-related support

---

Architecture overview

The repository is centered around a thin root façade and multiple focused subpackages, organized around small interfaces and adapter packages rather than a single large runtime framework.

Root façade

• requestCore.go
  • exposes the main RequestCoreModel
  • provides access to:
    • DB/query runner
    • ORM interface
    • request tools
    • response handler
    • parameter interface

Core layers

• libContext

  • framework-aware context initialization
  • tracing extraction
  • user and framework metadata handling

• libRequest

  • request lifecycle and persistence operations
  • initialization paths with and without logging
  • duplicate detection
  • context-aware updates

• libQuery

  • query runner abstraction
  • DB mode handling
  • execution helpers
  • ORM-oriented query support

• response

  • response handling
  • error response modeling
  • sanitization and web handler support

• libParams

  • parameter modeling and loading
  • networking, logging, DB, and security parameters

Framework adapters

• libGin
• libFiber
• libNetHttp
• webFramework

Supporting packages

• libLogger
• libTracing
• libError
• libValidate
• libCallApi
• libCrypto
• handlers
• swagger
• testingtools

Package reference

Package	Responsibility
requestCore.go	Root façade exposing the main interfaces
libContext	Detects and normalizes framework context (Gin, Fiber, net/http, testing); integrates tracing metadata and user identity extraction
libRequest	Request operations: initialization, duplicate checking, request insertion, updates with context, no-log initialization path
libQuery	Database/query layer with multiple DB modes: Oracle, PostgreSQL, SQLite, MySQL, Mock DB
response	Response generation and error handling utilities
libLogger	Logging utilities, including slog and Splunk-oriented integrations
libTracing	OpenTelemetry-related tracing and instrumentation helpers
libValidate	Input validation helpers
libCallApi	Utilities for calling external APIs and handling auth/multi-call scenarios
libCrypto	Cryptographic and security primitives
handlers	Reusable handler implementations for request, query, DML, pagination, recovery, and API call flows
testingtools	Test helpers, mocks, and simulation utilities

libCallApi remote API auth

Remote APIs can authenticate with OAuth2 (client_credentials, refresh_token, optional password grant) or fall back to BasicAuth when grant-type is not configured.

Example param.yaml:

remoteApis:
  partner-api:
    domain: https://api.partner.com
    name: partner-api
    auth:
      grant-type: client_credentials
      auth-uri: https://auth.partner.com/oauth/token
      client-id: partner-client

Secure values (existing pattern):

• remote-api#partner-api#client-secret
• remote-api#partner-api#client-id
• remote-api#partner-api#auth-uri (alias: auth-url)

---

Supported web frameworks

requestCore currently supports:

• Gin
• Fiber
• net/http (chi adapter in libChi/)
• testing

---

Requirements

• Go 1.27+
• A supported SQL database driver, depending on your chosen DB mode
• Optional:
  • OpenTelemetry
  • structured logging backend
  • ORM integration

---

Release Lines

This repository contains two independent Go modules with separate release streams:

Module	Import path	Tags	Status
Root (v1)	github.com/hmmftg/requestCore	v0.x.y, v1.x.y	Stable (v1.0 line)
v2	github.com/hmmftg/requestCore/v2	v2/v2.x.y	Alpha prerelease

• The root module is the stable v1 line. Upgrade from v0.28.1 using MIGRATION.md.
• The v2 module is a separate module under v2/ with its own go.mod, tags, and release workflow. See v2/README.md and v2/MIGRATION.md.
• v2-only commits do not trigger root module versioning.

---

Canonical setup: chi + net/http + sqlc + pgx/stdlib

For low-risk adoption, use sqlc in database/sql mode and connect PostgreSQL with pgx stdlib.

1) sqlc configuration

version: "2"
sql:
  - schema: "db/schema.sql"
    queries: "db/query.sql"
    engine: "postgresql"
    gen:
      go:
        package: "db"
        out: "internal/db"
        sql_package: "database/sql"

2) Open DB with pgx stdlib

import (
	"database/sql"

	_ "github.com/jackc/pgx/v5/stdlib"
)

db, err := sql.Open("pgx", "postgres://user:pass@localhost:5432/appdb?sslmode=disable")
if err != nil {
	panic(err)
}
defer db.Close()

3) Use chi route params with requestCore net/http parser

router := chi.NewRouter()
router.Get("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
	parser := libChi.InitParser(r, w)
	id := parser.GetUrlParam("id")
	_ = parser.SendJSONRespBody(http.StatusOK, map[string]string{"id": id})
})

This path keeps compatibility with the current database/sql-oriented query layer and enables incremental adoption.

---

Testing

The repository includes a strong testing story:

• framework-aware testing support
• mock DB mode
• fake API helpers
• package-level unit tests
• testing context support

This allows request handling, query execution, and framework adapters to be tested independently.

---

Optional advanced path: pgx-native sqlc mode

If you need sqlc generated code for pgx/v5 native interfaces (instead of database/sql), treat it as a separate compatibility track:

• keep current QueryRunnerInterface (database/sql) for backward compatibility
• add a parallel pgx-native runner contract and adapter implementation
• maintain parity tests for both backends:
  • query behavior and error mapping
  • DML behavior
  • tracing/logging hooks

Suggested parity matrix:

Capability	database/sql backend	pgx-native backend
Single-row query mapping	required	required
Multi-row query mapping	required	required
DML affected rows handling	required	required
Duplicate / no-data error mapping	required	required
Request-scoped tracing attributes	required	required
Existing handlers compatibility	required	required

This minimizes risk for existing users while allowing pgx-native optimization where needed.

---

Observability

requestCore is observability-friendly and includes support for:

• trace context extraction
• OpenTelemetry integration
• framework-aware logging
• structured logs via slog
• framework-specific logging adapters

This makes it suitable for services that need request-level visibility without hard-coding observability into business logic.

---

Database support

The query layer supports multiple DB modes, including:

• Oracle
• PostgreSQL
• SQLite
• MySQL
• Mock DB

This makes the library suitable for heterogeneous environments and for testing without a real database.

---

Design principles

requestCore follows these principles:

• composition over inheritance
• framework portability
• interface-driven design
• explicit abstractions
• observability by default
• testability first

---

Repository structure

requestCore/
├── requestCore.go
├── examples/
├── libContext/
├── libRequest/
├── libQuery/
├── libParams/
├── response/
├── libLogger/
├── libTracing/
├── libValidate/
├── libCallApi/
├── libCrypto/
├── handlers/
├── swagger/
├── testingtools/
├── libGin/
├── libFiber/
├── libNetHttp/
└── webFramework/

---

Documentation

Guides live in docs/:

• docs/MIGRATION.md — v0.28.1 → v1.x upgrade guide (kept at root for import-path discoverability)
• docs/OPENTELEMETRY_INTEGRATION.md
• docs/NETHTTP_IMPLEMENTATION_COMPLETE.md
• docs/DYNAMIC_HEADERS_GUIDE.md
• docs/VERSIONING.md
• docs/VERSIONING_SETUP.md
• docs/SETUP_COMPLETE.md

---

Articles

• Framework-Portable HTTP Handlers in Go with requestCore

---

v2: Generics-First Module

The v2/ directory contains a separate Go module (github.com/hmmftg/requestCore/v2) that builds on the root module with a generics-first API. It requires Go 1.27+ for generic methods.

What v2 adds

• Generic typed endpoints — handlers.Endpoint[Req, Resp] with typed lifecycle hooks (WithInitializer, WithFinalizer, WithPersistence)
• Generic resources — resources.ResourceBuilder[ID] + resources.Resource[ID cmp.Ordered] with 7 CRUD operations (TypedResource with 14 type params is an advanced alternative, overkill for simple CRUD)
• Typed session access — session.GetTyped[T] / session.SetTyped[T] (no runtime type assertions)
• Generic response helpers — response.Handler.OKTyped[Resp] / OKWithStatusTyped[Resp]
• Framework-agnostic routing — Gin, Fiber, chi, net/http via adapters
• Pluggable renderers — JSON, XML, text, CSV
• Background workers — bounded pool with retry, tracing, and mandatory webFramework.AddLog observability
• Scheduler — periodic background tasks
• CLI — requestcore code generator for handlers, resources, middleware, projects

Quick example

package main

import (
    "context"
    "log"
    "os/signal"
    "syscall"

    "github.com/hmmftg/requestCore/v2/app"
    "github.com/hmmftg/requestCore/v2/handlers"
    "github.com/hmmftg/requestCore/v2/renderers"
    "github.com/hmmftg/requestCore/v2/request"
)

type HealthReq struct{}

type HealthResp struct {
    Status string `json:"status"`
}

func main() {
    application, err := app.Bootstrap(app.Config{
        Framework: app.FrameworkChi,
        Renderer:  renderers.JSONRenderer{},
    })
    if err != nil {
        log.Fatal(err)
    }
    defer application.Close()

    // Register a typed GET endpoint using the canonical handler signature.
    err = handlers.GetEndpoint[HealthReq, HealthResp](
        application.Router, application.Executor, "/health",
        func(ctx *request.Context, req HealthReq) (HealthResp, error) {
            return HealthResp{Status: "healthy"}, nil
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    if err := application.StartWithContext(ctx, ":8080"); err != nil {
        log.Fatal(err)
    }
}

Documentation

• v2/README.md — full v2 module documentation
• v2/MIGRATION.md — v1-to-v2 migration guide
• v2/examples/simple/ — runnable example with typed endpoints, CRUD resource, sessions, and workers
• v2/examples/README.md — example documentation and smoke tests

---

Roadmap

This is a living document; items move as priorities shift.

• v2 stabilization — take the v2 generics-first kernel from alpha to a stable tag
• More framework adapters — Echo, standard library router, and others by community request
• Documentation site — consolidate the guides under docs/ into a rendered site (mkdocs or GitHub Pages)
• Demo assets — architecture diagram and an asciinema cast of the cross-framework examples
• Benchmark suite — publish comparable cross-framework overhead numbers (none exist yet)
• More database integrations — expand the libQuery DB mode matrix

See CHANGELOG.md for release history.

---

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, testing, lint, and commit conventions.

Suggested areas for contribution:

• framework adapters
• documentation
• observability enhancements
• request lifecycle helpers
• database integrations
• tests and examples

---

Community

Questions, ideas, or use cases? Open a GitHub Discussion — that's the place for Q&A and announcements. Bugs and feature requests go in Issues.

Note: Discussions must be enabled in repository Settings → General → Features. See CONTRIBUTING.md for the manual setup checklist.

---

Citation

If requestCore is useful in your work, please cite it:

@software{malek_mohammadi_2026_requestcore,
  author       = {Hamid Malek Mohammadi},
  title        = {requestCore: Framework-agnostic Go request lifecycle},
  year         = {2026},
  publisher    = {GitHub},
  url          = {https://github.com/hmmftg/requestCore},
  license      = {MIT}
}

See also CITATION.cff (renders a "Cite this repository" button on GitHub).

---

Security

Reporting a vulnerability? Please see SECURITY.md. Do not open a public issue for security reports.

---

License

MIT — Copyright (c) 2026 Hamid Malek Mohammadi.

Documentation

Overview

Package requestCore provides the core request processing pipeline framework.

Index

• type RequestCoreInterface
• type RequestCoreModel
  • func (m RequestCoreModel) GetDB() libQuery.QueryRunnerInterface
  • func (m RequestCoreModel) ORM() liborm.OrmInterface
  • func (m RequestCoreModel) Params() libParams.ParamInterface
  • func (m RequestCoreModel) RequestTools() libRequest.RequestInterface
  • func (m RequestCoreModel) Responder() response.ResponseHandler

Types

type RequestCoreInterface

type RequestCoreInterface interface {
	GetDB() libQuery.QueryRunnerInterface
	ORM() liborm.OrmInterface
	RequestTools() libRequest.RequestInterface
	Responder() response.ResponseHandler
	Params() libParams.ParamInterface
}

RequestCoreInterface defines the accessor methods for the core request processing model.

type RequestCoreModel

type RequestCoreModel struct {
	RequestInterface libRequest.RequestInterface
	QueryInterface   libQuery.QueryRunnerInterface
	OrmInterface     liborm.OrmInterface
	RespHandler      response.ResponseHandler
	ParamMap         libParams.ParamInterface
}

RequestCoreModel is the central model holding query, ORM, request, response, and parameter interfaces.

func (RequestCoreModel) GetDB

func (m RequestCoreModel) GetDB() libQuery.QueryRunnerInterface

GetDB returns the query runner interface for database access.

func (RequestCoreModel) ORM

func (m RequestCoreModel) ORM() liborm.OrmInterface

ORM returns the ORM interface for Gorm-based database access.

func (RequestCoreModel) Params

func (m RequestCoreModel) Params() libParams.ParamInterface

Params returns the application parameter interface.

func (RequestCoreModel) RequestTools

func (m RequestCoreModel) RequestTools() libRequest.RequestInterface

RequestTools returns the request interface for request lifecycle management.

func (RequestCoreModel) Responder

func (m RequestCoreModel) Responder() response.ResponseHandler

Responder returns the response handler for formatting HTTP responses.