From 367f67b8ab23024a46c4a92907a25ce04a54ab0f Mon Sep 17 00:00:00 2001 From: Festus Date: Thu, 5 Feb 2026 13:32:07 +0100 Subject: [PATCH] updated readme --- README.md | 87 ++++++++++++++++++++++++++++++ USAGE.md | 77 ++++++++++++++++++++++++++ adapters/grpc/client.go | 4 +- adapters/http/client.go | 4 +- adapters/kafka/consumer.go | 2 +- adapters/rabbitmq/consumer.go | 2 +- adapters/rabbitmq/producer.go | 2 +- adapters/rabbitmq/rabbitmq_test.go | 2 +- examples/kafka/consumer/main.go | 4 +- examples/kafka/producer/main.go | 2 +- examples/network/grpc/main.go | 2 +- examples/network/http/main.go | 4 +- examples/rabbitmq/consumer/main.go | 4 +- examples/rabbitmq/producer/main.go | 4 +- go.mod | 8 +-- go.sum | 2 + network/options.go | 2 +- 17 files changed, 189 insertions(+), 23 deletions(-) create mode 100644 USAGE.md diff --git a/README.md b/README.md index f9b7b15..44af26d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # microkit +[![Go Reference](https://pkg.go.dev/badge/github.com/festus/microkit.svg)](https://pkg.go.dev/github.com/festus/microkit) +[![Go Report Card](https://goreportcard.com/badge/github.com/festus/microkit)](https://goreportcard.com/report/github.com/festus/microkit) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + An opinionated Go toolkit that simplifies building microservices by providing clean abstractions over common infrastructure tools like messaging, networking, and service communication. --- @@ -21,6 +25,89 @@ It’s a toolkit you can adopt incrementally. --- +## Getting Started + +### Installation + +```bash +go get github.com/festus/microkit +``` + +### Quick Start + +#### HTTP Client with Retry + +```go +package main + +import ( + "context" + "fmt" + "time" + + "github.com/festus/microkit/adapters/http" + "github.com/festus/microkit/network" +) + +func main() { + client := http.NewClient(10 * time.Second) + defer client.Close() + + resp, err := client.Get(context.Background(), "https://api.example.com", + network.WithHeader("Authorization", "Bearer token"), + network.WithRetry(3, 100*time.Millisecond, 2*time.Second, 2.0), + ) + if err != nil { + panic(err) + } + + fmt.Printf("Response: %d\n", resp.StatusCode) +} +``` + +#### Kafka Consumer with Retry/DLQ + +```go +package main + +import ( + "context" + "fmt" + "time" + + "github.com/festus/microkit/adapters/kafka" + "github.com/festus/microkit/internal/retry" +) + +func main() { + conn := kafka.NewConnection([]string{"localhost:9092"}) + + config := kafka.ConsumerConfig{ + RetryConfig: retry.Config{ + MaxAttempts: 3, + InitialDelay: 100 * time.Millisecond, + MaxDelay: 2 * time.Second, + Multiplier: 2.0, + }, + EnableDLQ: true, + DLQTopic: "orders-dlq", + } + + consumer := kafka.NewConsumerWithConfig(conn, "orders", "order-service", config) + defer consumer.Close() + + consumer.Subscribe(context.Background(), func(msg []byte) error { + fmt.Printf("Processing: %s\n", string(msg)) + // Your business logic here + return nil + }) + + select {} // Keep running +} +``` + +--- + ## Current Focus - Messaging abstractions diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..1200ad5 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,77 @@ +# Installation + +```bash +go get github.com/festus/microkit +``` + +# Quick Start + +## HTTP Client + +```go +package main + +import ( + "context" + "time" + + "github.com/festus/microkit/adapters/http" + "github.com/festus/microkit/network" +) + +func main() { + client := http.NewClient(10 * time.Second) + defer client.Close() + + resp, err := client.Get(context.Background(), "https://api.example.com", + network.WithHeader("Authorization", "Bearer token"), + network.WithRetry(3, 100*time.Millisecond, 2*time.Second, 2.0), + ) + // Handle response... +} +``` + +## Kafka Producer + +```go +package main + +import ( + "context" + + "github.com/festus/microkit/adapters/kafka" + "github.com/festus/microkit/messaging" +) + +func main() { + conn := kafka.NewConnection([]string{"localhost:9092"}) + producer := kafka.NewProducer(conn, "my-topic") + defer producer.Close() + + producer.Publish(context.Background(), []byte("key"), []byte("message")) +} +``` + +## RabbitMQ Consumer + +```go +package main + +import ( + "context" + + "github.com/festus/microkit/adapters/rabbitmq" + "github.com/festus/microkit/messaging" +) + +func main() { + producer, _ := rabbitmq.NewProducer( + rabbitmq.WithURL("amqp://localhost"), + ) + defer producer.Close() + + producer.Publish(context.Background(), "queue.name", messaging.Message{ + Payload: []byte(`{"data": "value"}`), + }) +} +``` \ No newline at end of file diff --git a/adapters/grpc/client.go b/adapters/grpc/client.go index b8b53cc..85261d0 100644 --- a/adapters/grpc/client.go +++ b/adapters/grpc/client.go @@ -4,8 +4,8 @@ import ( "context" "time" - "github.com/festech-cloud/microkit/network" - "github.com/festech-cloud/microkit/internal/retry" + "github.com/festus/microkit/network" + "github.com/festus/microkit/internal/retry" "google.golang.org/grpc" "google.golang.org/grpc/credentials/insecure" ) diff --git a/adapters/http/client.go b/adapters/http/client.go index fd445d4..ed54878 100644 --- a/adapters/http/client.go +++ b/adapters/http/client.go @@ -7,8 +7,8 @@ import ( "net/http" "time" - "github.com/festech-cloud/microkit/network" - "github.com/festech-cloud/microkit/internal/retry" + "github.com/festus/microkit/network" + "github.com/festus/microkit/internal/retry" ) type Client struct { diff --git a/adapters/kafka/consumer.go b/adapters/kafka/consumer.go index 78c1f48..5c6ff53 100644 --- a/adapters/kafka/consumer.go +++ b/adapters/kafka/consumer.go @@ -6,7 +6,7 @@ import ( "log" kafka "github.com/segmentio/kafka-go" - "github.com/festech-cloud/microkit/internal/retry" + "github.com/festus/microkit/internal/retry" ) type ConsumerConfig struct { diff --git a/adapters/rabbitmq/consumer.go b/adapters/rabbitmq/consumer.go index 2c5603c..8f120c1 100644 --- a/adapters/rabbitmq/consumer.go +++ b/adapters/rabbitmq/consumer.go @@ -4,7 +4,7 @@ import ( "context" "log" - "github.com/festech-cloud/microkit/messaging" + "github.com/festus/microkit/messaging" "github.com/rabbitmq/amqp091-go" ) diff --git a/adapters/rabbitmq/producer.go b/adapters/rabbitmq/producer.go index 21205af..09ff30a 100644 --- a/adapters/rabbitmq/producer.go +++ b/adapters/rabbitmq/producer.go @@ -3,7 +3,7 @@ package rabbitmq import ( "context" - "github.com/festech-cloud/microkit/messaging" + "github.com/festus/microkit/messaging" "github.com/rabbitmq/amqp091-go" ) diff --git a/adapters/rabbitmq/rabbitmq_test.go b/adapters/rabbitmq/rabbitmq_test.go index 7ae6bbc..feaea0d 100644 --- a/adapters/rabbitmq/rabbitmq_test.go +++ b/adapters/rabbitmq/rabbitmq_test.go @@ -7,7 +7,7 @@ import ( "testing" "time" - "github.com/festech-cloud/microkit/messaging" + "github.com/festus/microkit/messaging" "github.com/testcontainers/testcontainers-go" "github.com/testcontainers/testcontainers-go/wait" ) diff --git a/examples/kafka/consumer/main.go b/examples/kafka/consumer/main.go index bc90fd7..85d5cea 100644 --- a/examples/kafka/consumer/main.go +++ b/examples/kafka/consumer/main.go @@ -7,8 +7,8 @@ import ( "math/rand" "time" - "github.com/festech-cloud/microkit/adapters/kafka" - "github.com/festech-cloud/microkit/internal/retry" + "github.com/festus/microkit/adapters/kafka" + "github.com/festus/microkit/internal/retry" ) func main() { diff --git a/examples/kafka/producer/main.go b/examples/kafka/producer/main.go index be91384..b52a12c 100644 --- a/examples/kafka/producer/main.go +++ b/examples/kafka/producer/main.go @@ -5,7 +5,7 @@ import ( "fmt" "log" - "github.com/festech-cloud/microkit/adapters/kafka" + "github.com/festus/microkit/adapters/kafka" ) func main() { diff --git a/examples/network/grpc/main.go b/examples/network/grpc/main.go index 94f8a8c..78e7fdf 100644 --- a/examples/network/grpc/main.go +++ b/examples/network/grpc/main.go @@ -5,7 +5,7 @@ import ( "log" "time" - "github.com/festech-cloud/microkit/adapters/grpc" + "github.com/festus/microkit/adapters/grpc" ) func main() { diff --git a/examples/network/http/main.go b/examples/network/http/main.go index f8a8321..bb2e8fc 100644 --- a/examples/network/http/main.go +++ b/examples/network/http/main.go @@ -6,8 +6,8 @@ import ( "log" "time" - "github.com/festech-cloud/microkit/adapters/http" - "github.com/festech-cloud/microkit/network" + "github.com/festus/microkit/adapters/http" + "github.com/festus/microkit/network" ) func main() { diff --git a/examples/rabbitmq/consumer/main.go b/examples/rabbitmq/consumer/main.go index 8e6368b..7f4adcd 100644 --- a/examples/rabbitmq/consumer/main.go +++ b/examples/rabbitmq/consumer/main.go @@ -5,8 +5,8 @@ import ( "fmt" "log" - "github.com/festech-cloud/microkit/adapters/rabbitmq" - "github.com/festech-cloud/microkit/messaging" + "github.com/festus/microkit/adapters/rabbitmq" + "github.com/festus/microkit/messaging" ) func main() { diff --git a/examples/rabbitmq/producer/main.go b/examples/rabbitmq/producer/main.go index 3ed8232..a3ad741 100644 --- a/examples/rabbitmq/producer/main.go +++ b/examples/rabbitmq/producer/main.go @@ -5,8 +5,8 @@ import ( "fmt" "log" - "github.com/festech-cloud/microkit/adapters/rabbitmq" - "github.com/festech-cloud/microkit/messaging" + "github.com/festus/microkit/adapters/rabbitmq" + "github.com/festus/microkit/messaging" ) func main() { diff --git a/go.mod b/go.mod index c095e5e..16a06f9 100644 --- a/go.mod +++ b/go.mod @@ -1,9 +1,10 @@ -module github.com/festech-cloud/microkit +module github.com/festus/microkit go 1.24.9 require ( github.com/IBM/sarama v1.46.3 + github.com/festech-cloud/microkit v0.1.0 github.com/rabbitmq/amqp091-go v1.10.0 github.com/segmentio/kafka-go v0.4.50 github.com/testcontainers/testcontainers-go v0.40.0 @@ -36,6 +37,7 @@ require ( github.com/go-ole/go-ole v1.2.6 // indirect github.com/golang/snappy v0.0.4 // indirect github.com/google/uuid v1.6.0 // indirect + github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 // indirect github.com/hashicorp/go-uuid v1.0.3 // indirect github.com/jcmturner/aescts/v2 v2.0.0 // indirect github.com/jcmturner/dnsutils/v2 v2.0.0 // indirect @@ -69,11 +71,9 @@ require ( go.opentelemetry.io/auto/sdk v1.2.1 // indirect go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect go.opentelemetry.io/otel v1.40.0 // indirect - go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 // indirect go.opentelemetry.io/otel/metric v1.40.0 // indirect - go.opentelemetry.io/otel/sdk/metric v1.40.0 // indirect + go.opentelemetry.io/otel/sdk v1.40.0 // indirect go.opentelemetry.io/otel/trace v1.40.0 // indirect - go.opentelemetry.io/proto/otlp v1.9.0 // indirect golang.org/x/crypto v0.44.0 // indirect golang.org/x/net v0.47.0 // indirect golang.org/x/sys v0.40.0 // indirect diff --git a/go.sum b/go.sum index ac0bb61..b1545ac 100644 --- a/go.sum +++ b/go.sum @@ -45,6 +45,8 @@ github.com/ebitengine/purego v0.8.4 h1:CF7LEKg5FFOsASUj0+QwaXf8Ht6TlFxg09+S9wz0o github.com/ebitengine/purego v0.8.4/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ= github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg= github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/festech-cloud/microkit v0.1.0 h1:g3WE6pJfSrskkCMBfe8uueRdzNkQZPUj/BlAz2C/fus= +github.com/festech-cloud/microkit v0.1.0/go.mod h1:wvaJf6cujNXdqZvCXZMCeGCTrgEQy5fihv5qbad4JlA= github.com/fortytw2/leaktest v1.3.0 h1:u8491cBMTQ8ft8aeV+adlcytMZylmA5nnwwkRZjI8vw= github.com/fortytw2/leaktest v1.3.0/go.mod h1:jDsjWgpAGjm2CA7WthBh/CdZYEPF31XHquHwclZch5g= github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= diff --git a/network/options.go b/network/options.go index 2d9462b..f92893c 100644 --- a/network/options.go +++ b/network/options.go @@ -3,7 +3,7 @@ package network import ( "time" - "github.com/festech-cloud/microkit/internal/retry" + "github.com/festus/microkit/internal/retry" ) // Option configures network requests.