README
¶
isp-kit
A powerful and lightweight application lifecycle management framework and utility suite for building scalable Go microservices.
🌟 Overview
isp-kit provides a unified ecosystem for developing production-ready services. From configuration management to distributed tracing, it offers a structured approach to common microservice patterns, allowing you to focus on business logic rather than boilerplate.
📦 Features
- Application Lifecycle - Lightweight application management with graceful startup/shutdown
- Configuration Management - Flexible config system with YAML, environment variables, and hot-reload support
- Database Integration - PostgreSQL client with transaction support, migrations, and automatic schema management
- Message Queues - High-level abstractions for Kafka, RabbitMQ, and STOMP with middleware chains
- HTTP & gRPC - Production-ready servers and clients with middleware, metrics, and tracing
- Distributed Tracing - OpenTelemetry integration across all transport layers
- Metrics Collection - Prometheus-based metrics for HTTP, gRPC, Kafka, RabbitMQ, SQL, and background jobs
- Error Handling - Structured error types for HTTP and gRPC with business error codes
- Cluster Coordination - Client-side functionality for distributed configuration and service discovery
- Health Checks - Standardized health check endpoints with component-level status
📚 Core Packages
Application & Bootstrap
| Package | Description |
|---|---|
app |
Lightweight application lifecycle management with Runner components |
bootstrap |
Unified initialization framework for configuration, logging, and infrastructure |
config |
Flexible configuration management with multiple sources and type-safe retrieval |
Database & Storage
| Package | Description |
|---|---|
db |
PostgreSQL client with sqlx/pgx integration and transaction support |
dbx |
Extended database client with migrations and schema management |
dbrx |
Dynamic database client with hot-reload capability |
Messaging
| Package | Description |
|---|---|
kafkax |
High-level Kafka abstraction with franz-go client |
grmqx |
RabbitMQ wrapper with automatic topology declaration |
stompx |
STOMP protocol wrapper for message brokers |
Communication
| Package | Description |
|---|---|
http |
Core HTTP server with middleware support |
http/httpcli |
High-level HTTP client with retries and middleware |
grpc |
gRPC server and client with hot-swappable handlers |
grpc/client |
gRPC client with load balancing and observability |
Observability
| Package | Description |
|---|---|
log |
Structured logging adapter based on Uber Zap |
metrics |
Prometheus metrics registry and storage types |
observability/tracing |
OpenTelemetry distributed tracing integration |
observability/sentry |
Sentry error tracking and event monitoring |
Utilities
| Package | Description |
|---|---|
healthcheck |
Health check registry and JSON endpoint |
requestid |
Request ID management across contexts |
retry |
Exponential backoff retry utilities |
shutdown |
Process termination signal handling |
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app provides a lightweight application lifecycle management framework.
|
Package app provides a lightweight application lifecycle management framework. |
|
Package bootstrap provides a unified initialization framework for isp-kit applications.
|
Package bootstrap provides a unified initialization framework for isp-kit applications. |
|
Package cluster provides client-side functionality for connecting to a isp-config-service in a distributed system.
|
Package cluster provides client-side functionality for connecting to a isp-config-service in a distributed system. |
|
Package common_endpoints provides common HTTP endpoint descriptors for services.
|
Package common_endpoints provides common HTTP endpoint descriptors for services. |
|
Package config provides a flexible configuration management system with support for multiple sources, environment variable overrides, and type-safe value retrieval.
|
Package config provides a flexible configuration management system with support for multiple sources, environment variable overrides, and type-safe value retrieval. |
|
Package db provides a PostgreSQL database client wrapper that integrates sqlx with pgx, offering transaction support, query tracing, and automatic snake_case field mapping for struct tags.
|
Package db provides a PostgreSQL database client wrapper that integrates sqlx with pgx, offering transaction support, query tracing, and automatic snake_case field mapping for struct tags. |
|
jsonb
Package jsonb provides a custom type for handling JSONB data in PostgreSQL.
|
Package jsonb provides a custom type for handling JSONB data in PostgreSQL. |
|
query
Package query provides a fluent query builder for PostgreSQL using the Masterminds/squirrel library with dollar-sign placeholder formatting.
|
Package query provides a fluent query builder for PostgreSQL using the Masterminds/squirrel library with dollar-sign placeholder formatting. |
|
Package dbrx provides a dynamic database client that supports runtime configuration updates.
|
Package dbrx provides a dynamic database client that supports runtime configuration updates. |
|
Package dbx extends the db package with additional features including automatic schema creation, database migrations via goose, and connection pool configuration.
|
Package dbx extends the db package with additional features including automatic schema creation, database migrations via goose, and connection pool configuration. |
|
migration
Package migration provides database migration functionality using the goose library.
|
Package migration provides database migration functionality using the goose library. |
|
Package grmqx provides a high-level wrapper for the RabbitMQ client, offering automatic topology declaration, integration with metrics and tracing, flexible retry policies, and contextual logging.
|
Package grmqx provides a high-level wrapper for the RabbitMQ client, offering automatic topology declaration, integration with metrics and tracing, flexible retry policies, and contextual logging. |
|
batch_handler
Package batch_handler provides batch message processing for RabbitMQ consumers.
|
Package batch_handler provides batch message processing for RabbitMQ consumers. |
|
handler
Package handler provides synchronous message processing for RabbitMQ consumers.
|
Package handler provides synchronous message processing for RabbitMQ consumers. |
|
Package grpc provides a gRPC server and client implementation for the ISP kit framework.
|
Package grpc provides a gRPC server and client implementation for the ISP kit framework. |
|
apierrors
Package apierrors provides structured error handling for gRPC services.
|
Package apierrors provides structured error handling for gRPC services. |
|
client
Package client provides a gRPC client implementation with built-in load balancing, middleware support, and observability features.
|
Package client provides a gRPC client implementation with built-in load balancing, middleware support, and observability features. |
|
client/request
Package request provides a fluent builder for constructing and executing gRPC requests.
|
Package request provides a fluent builder for constructing and executing gRPC requests. |
|
endpoint
Package endpoint provides a higher-level abstraction for building gRPC handlers.
|
Package endpoint provides a higher-level abstraction for building gRPC handlers. |
|
endpoint/grpclog
Package grpclog provides logging middleware for gRPC server handlers.
|
Package grpclog provides logging middleware for gRPC server handlers. |
|
Package healthcheck provides utilities for implementing and managing health checks in applications.
|
Package healthcheck provides utilities for implementing and managing health checks in applications. |
|
Package http provides core HTTP server functionality and types for building REST and SOAP services.
|
Package http provides core HTTP server functionality and types for building REST and SOAP services. |
|
apierrors
Package apierrors provides HTTP error handling with structured error responses.
|
Package apierrors provides HTTP error handling with structured error responses. |
|
endpoint
Package endpoint provides a high-level abstraction for building HTTP endpoints with automatic request/response handling, validation, and middleware support.
|
Package endpoint provides a high-level abstraction for building HTTP endpoints with automatic request/response handling, validation, and middleware support. |
|
endpoint/buffer
Package buffer provides a ResponseWriter wrapper that buffers request and response bodies.
|
Package buffer provides a ResponseWriter wrapper that buffers request and response bodies. |
|
endpoint/httplog
Package httplog provides HTTP request/response logging middleware.
|
Package httplog provides HTTP request/response logging middleware. |
|
httpcli
Package httpcli provides a high-level HTTP client with support for middleware, retries, and flexible request/response handling.
|
Package httpcli provides a high-level HTTP client with support for middleware, retries, and flexible request/response handling. |
|
httpclix
Package httpclix provides extended HTTP client functionality including load balancing, logging, and observability middleware.
|
Package httpclix provides extended HTTP client functionality including load balancing, logging, and observability middleware. |
|
router
Package router provides HTTP request routing with metrics integration.
|
Package router provides HTTP request routing with metrics integration. |
|
soap
Package soap provides SOAP message handling for XML-based web services.
|
Package soap provides SOAP message handling for XML-based web services. |
|
soap/client
Package client provides a SOAP client for invoking SOAP web services.
|
Package client provides a SOAP client for invoking SOAP web services. |
|
bench
module
|
|
|
Package infra provides a wrapper around the standard library's net/http HTTP server with graceful shutdown support.
|
Package infra provides a wrapper around the standard library's net/http HTTP server with graceful shutdown support. |
|
pprof
Package pprof provides utilities for integrating Go's pprof profiling tools with an HTTP server.
|
Package pprof provides utilities for integrating Go's pprof profiling tools with an HTTP server. |
|
Package json provides a high-performance JSON encoder/decoder based on jsoniter.
|
Package json provides a high-performance JSON encoder/decoder based on jsoniter. |
|
nolint:ireturn,lll,unparam,gosec
|
nolint:ireturn,lll,unparam,gosec |
|
consumer
Package consumer provides a high-level abstraction for consuming messages from Apache Kafka topics.
|
Package consumer provides a high-level abstraction for consuming messages from Apache Kafka topics. |
|
handler
Package handler provides synchronous message processing with support for retry logic, commit handling, and middleware chains for cross-cutting concerns like logging, metrics, and panic recovery.
|
Package handler provides synchronous message processing with support for retry logic, commit handling, and middleware chains for cross-cutting concerns like logging, metrics, and panic recovery. |
|
publisher
Package publisher provides a high-level abstraction for publishing messages to Apache Kafka topics.
|
Package publisher provides a high-level abstraction for publishing messages to Apache Kafka topics. |
|
Package lb provides load balancing functionality with a Round Robin algorithm.
|
Package lb provides load balancing functionality with a Round Robin algorithm. |
|
Package log provides a logging adapter built on top of Uber's Zap library.
|
Package log provides a logging adapter built on top of Uber's Zap library. |
|
file
Package file provides log file output with rotation using lumberjack.
|
Package file provides log file output with rotation using lumberjack. |
|
logutil
Package logutil provides utility functions for logging.
|
Package logutil provides utility functions for logging. |
|
Package metrics provides a Prometheus-based metrics collection system with support for various subsystems including HTTP, gRPC, Kafka, RabbitMQ, SQL, and background jobs.
|
Package metrics provides a Prometheus-based metrics collection system with support for various subsystems including HTTP, gRPC, Kafka, RabbitMQ, SQL, and background jobs. |
|
app_metrics
Package app_metrics provides application-level metrics including log sampling statistics.
|
Package app_metrics provides application-level metrics including log sampling statistics. |
|
bgjob_metrics
Package bgjob_metrics provides Prometheus metric collectors for background job processing.
|
Package bgjob_metrics provides Prometheus metric collectors for background job processing. |
|
db_metrics
Package db_metrics provides utilities for registering database connection pool metrics.
|
Package db_metrics provides utilities for registering database connection pool metrics. |
|
grpc_metrics
Package grpc_metrics provides Prometheus metric collectors for gRPC server and client operations.
|
Package grpc_metrics provides Prometheus metric collectors for gRPC server and client operations. |
|
http_metrics
Package http_metrics provides Prometheus metric collectors for HTTP server and client operations.
|
Package http_metrics provides Prometheus metric collectors for HTTP server and client operations. |
|
kafka_metrics
Package kafka_metrics provides Prometheus metric collectors for Kafka producer and consumer operations.
|
Package kafka_metrics provides Prometheus metric collectors for Kafka producer and consumer operations. |
|
rabbitmq_metrics
Package rabbitmq_metrics provides Prometheus metric collectors for RabbitMQ publisher and consumer operations.
|
Package rabbitmq_metrics provides Prometheus metric collectors for RabbitMQ publisher and consumer operations. |
|
sql_metrics
Package sql_metrics provides Prometheus metric collectors for SQL query execution.
|
Package sql_metrics provides Prometheus metric collectors for SQL query execution. |
|
observability
|
|
|
sentry
Package sentry provides integration with Sentry for error tracking and event monitoring.
|
Package sentry provides integration with Sentry for error tracking and event monitoring. |
|
tracing/grpc
Package grpc provides utilities for gRPC tracing integration.
|
Package grpc provides utilities for gRPC tracing integration. |
|
tracing/grpc/client_tracing
Package client_tracing provides gRPC client middleware for distributed tracing.
|
Package client_tracing provides gRPC client middleware for distributed tracing. |
|
tracing/grpc/server_tracing
Package server_tracing provides gRPC server middleware for distributed tracing.
|
Package server_tracing provides gRPC server middleware for distributed tracing. |
|
tracing/http/client_tracing
Package client_tracing provides HTTP client middleware for distributed tracing.
|
Package client_tracing provides HTTP client middleware for distributed tracing. |
|
tracing/http/server_tracing
Package server_tracing provides HTTP server middleware for distributed tracing.
|
Package server_tracing provides HTTP server middleware for distributed tracing. |
|
tracing/rabbitmq
Package rabbitmq provides utilities for RabbitMQ tracing integration.
|
Package rabbitmq provides utilities for RabbitMQ tracing integration. |
|
tracing/rabbitmq/consumer_tracing
Package consumer_tracing provides RabbitMQ consumer middleware for distributed tracing.
|
Package consumer_tracing provides RabbitMQ consumer middleware for distributed tracing. |
|
tracing/rabbitmq/publisher_tracing
Package publisher_tracing provides RabbitMQ publisher middleware for distributed tracing.
|
Package publisher_tracing provides RabbitMQ publisher middleware for distributed tracing. |
|
tracing/sql_tracing
Package sql_tracing provides pgx v5 query tracing for distributed tracing.
|
Package sql_tracing provides pgx v5 query tracing for distributed tracing. |
|
Package panic_recovery provides utilities for recovering from panics in Go applications.
|
Package panic_recovery provides utilities for recovering from panics in Go applications. |
|
Package rc provides a configuration management system with support for override merging, validation, and hot-reloading capabilities.
|
Package rc provides a configuration management system with support for override merging, validation, and hot-reloading capabilities. |
|
schema
Package schema provides JSON schema generation for Go structs with support for custom field properties, validation constraints, and tag-based configuration.
|
Package schema provides JSON schema generation for Go structs with support for custom field properties, validation constraints, and tag-based configuration. |
|
Package requestid provides utilities for managing request IDs in Go applications.
|
Package requestid provides utilities for managing request IDs in Go applications. |
|
Package retry provides utilities for performing operations with retry logic.
|
Package retry provides utilities for performing operations with retry logic. |
|
Package shutdown provides utilities for handling process termination signals.
|
Package shutdown provides utilities for handling process termination signals. |
|
Package stompx provides a high-level wrapper over the STOMP protocol, implementing convenient tools for creating message consumers and publishers, with support for middleware, logging, retries, and management of consumer and publisher groups.
|
Package stompx provides a high-level wrapper over the STOMP protocol, implementing convenient tools for creating message consumers and publishers, with support for middleware, logging, retries, and management of consumer and publisher groups. |
|
consumer
Package consumer provides functionality for consuming messages from a STOMP broker.
|
Package consumer provides functionality for consuming messages from a STOMP broker. |
|
handler
Package handler provides functionality for processing STOMP messages and handling results.
|
Package handler provides functionality for processing STOMP messages and handling results. |
|
publisher
Package publisher provides functionality for publishing messages to a STOMP broker.
|
Package publisher provides functionality for publishing messages to a STOMP broker. |
|
Package test provides a test helper that wraps testing.T and automatically initializes configuration and logger for unit and integration tests.
|
Package test provides a test helper that wraps testing.T and automatically initializes configuration and logger for unit and integration tests. |
|
dbt
Package dbt provides test helpers for database operations using dbx.
|
Package dbt provides test helpers for database operations using dbx. |
|
fake
Package fake provides utilities for generating fake test data using the faker library.
|
Package fake provides utilities for generating fake test data using the faker library. |
|
grmqt
Package grmqt provides test helpers for RabbitMQ operations.
|
Package grmqt provides test helpers for RabbitMQ operations. |
|
grpct
Package grpct provides test helpers for gRPC server and client operations.
|
Package grpct provides test helpers for gRPC server and client operations. |
|
httpt
Package httpt provides test helpers for HTTP server and client operations.
|
Package httpt provides test helpers for HTTP server and client operations. |
|
kafkat
Package kafkat provides test helpers for Kafka operations using the franz-go client.
|
Package kafkat provides test helpers for Kafka operations using the franz-go client. |
|
rct
Package rct provides test helpers for remote configuration validation.
|
Package rct provides test helpers for remote configuration validation. |
|
stompt
Package stompt provides test helpers for STOMP messaging operations (typically used with ActiveMQ).
|
Package stompt provides test helpers for STOMP messaging operations (typically used with ActiveMQ). |
|
Package validator provides a structured validation adapter using the go-playground/validator library with English translations for error messages.
|
Package validator provides a structured validation adapter using the go-playground/validator library with English translations for error messages. |
|
Package worker provides a configurable worker for periodic task execution with concurrency control and graceful shutdown support.
|
Package worker provides a configurable worker for periodic task execution with concurrency control and graceful shutdown support. |
Click to show internal directories.
Click to hide internal directories.