biucingcli 0.9.1__py3-none-any.whl

biucingcli/template_data/microservice/template/internal/repository/.gitkeep

@@ -0,0 +1 @@
+

biucingcli/template_data/microservice/template/internal/router/router.go

@@ -0,0 +1,26 @@
+package router
+
+import "{{MODULE_NAME}}/internal/config"
+import "{{MODULE_NAME}}/internal/handler"
+import "{{MODULE_NAME}}/internal/service"
+
+import "github.com/gin-gonic/gin"
+
+func New(cfg config.Config) *gin.Engine {
+	engine := gin.Default()
+
+	healthService := service.NewHealthService(
+		cfg.Service.Name,
+		cfg.Service.GRPCPort,
+		cfg.Store.Driver,
+	)
+	healthHandler := handler.NewHealthHandler(healthService)
+	healthHandler.RegisterRoutes(engine)
+
+	apiGroup := engine.Group("/api/v1")
+	pingService := service.NewPingService(cfg.Service.Name, "{{PROTO_PACKAGE}}")
+	pingHandler := handler.NewPingHandler(pingService)
+	pingHandler.RegisterRoutes(apiGroup)
+
+	return engine
+}

biucingcli/template_data/microservice/template/internal/runtime/server.go

@@ -0,0 +1,116 @@
+package runtime
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"time"
+
+	"{{MODULE_NAME}}/internal/config"
+
+	"google.golang.org/grpc"
+)
+
+type GRPCServer interface {
+	Serve(net.Listener) error
+	GracefulStop()
+	Stop()
+	SetServing(bool)
+}
+
+func NewHTTPServer(cfg config.Config, handler http.Handler) *http.Server {
+	return &http.Server{
+		Addr:              ":" + cfg.Service.HTTPPort,
+		Handler:           handler,
+		ReadTimeout:       time.Duration(cfg.Server.ReadTimeoutSeconds) * time.Second,
+		ReadHeaderTimeout: time.Duration(cfg.Server.ReadHeaderTimeoutSeconds) * time.Second,
+		WriteTimeout:      time.Duration(cfg.Server.WriteTimeoutSeconds) * time.Second,
+		IdleTimeout:       time.Duration(cfg.Server.IdleTimeoutSeconds) * time.Second,
+	}
+}
+
+func CheckHealth(ctx context.Context, url string) error {
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return err
+	}
+	response, err := http.DefaultClient.Do(request)
+	if err != nil {
+		return err
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		return errors.New("health endpoint returned " + response.Status)
+	}
+	return nil
+}
+
+func Serve(
+	ctx context.Context,
+	httpServer *http.Server,
+	httpListener net.Listener,
+	grpcServer GRPCServer,
+	grpcListener net.Listener,
+	shutdownTimeout time.Duration,
+) error {
+	type result struct {
+		name string
+		err  error
+	}
+	serveResults := make(chan result, 2)
+	go func() {
+		serveResults <- result{name: "HTTP", err: httpServer.Serve(httpListener)}
+	}()
+	go func() {
+		serveResults <- result{name: "gRPC", err: grpcServer.Serve(grpcListener)}
+	}()
+
+	var serveErr error
+	select {
+	case result := <-serveResults:
+		if !isExpectedServeError(result.err) {
+			serveErr = fmt.Errorf("%s server: %w", result.name, result.err)
+		}
+	case <-ctx.Done():
+	}
+
+	grpcServer.SetServing(false)
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
+	defer cancel()
+
+	httpDone := make(chan error, 1)
+	go func() {
+		httpDone <- httpServer.Shutdown(shutdownCtx)
+	}()
+	grpcDone := make(chan struct{})
+	go func() {
+		grpcServer.GracefulStop()
+		close(grpcDone)
+	}()
+
+	var shutdownErr error
+	select {
+	case err := <-httpDone:
+		if err != nil {
+			shutdownErr = errors.Join(shutdownErr, fmt.Errorf("HTTP shutdown: %w", err))
+		}
+	case <-shutdownCtx.Done():
+		_ = httpServer.Close()
+		shutdownErr = errors.Join(shutdownErr, shutdownCtx.Err())
+	}
+
+	select {
+	case <-grpcDone:
+	case <-shutdownCtx.Done():
+		grpcServer.Stop()
+		shutdownErr = errors.Join(shutdownErr, shutdownCtx.Err())
+	}
+
+	return errors.Join(serveErr, shutdownErr)
+}
+
+func isExpectedServeError(err error) bool {
+	return err == nil || errors.Is(err, http.ErrServerClosed) || errors.Is(err, grpc.ErrServerStopped)
+}

biucingcli/template_data/microservice/template/internal/runtime/server_test.go

@@ -0,0 +1,161 @@
+package runtime
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"{{MODULE_NAME}}/internal/config"
+
+	"google.golang.org/grpc"
+)
+
+func TestCheckHealthRequiresSuccessfulResponse(t *testing.T) {
+	healthServer := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		if request.URL.Path != "/healthz" {
+			writer.WriteHeader(http.StatusNotFound)
+			return
+		}
+		writer.WriteHeader(http.StatusOK)
+	}))
+	defer healthServer.Close()
+
+	if err := CheckHealth(context.Background(), healthServer.URL+"/healthz"); err != nil {
+		t.Fatal(err)
+	}
+	if err := CheckHealth(context.Background(), healthServer.URL+"/missing"); err == nil {
+		t.Fatal("expected a non-success status to fail the health check")
+	}
+}
+
+type fakeGRPCServer struct {
+	stopOnce       sync.Once
+	stopped        chan struct{}
+	servingChanges chan bool
+	blockGraceful  bool
+	forcedStop     chan struct{}
+}
+
+func newFakeGRPCServer(blockGraceful bool) *fakeGRPCServer {
+	return &fakeGRPCServer{
+		stopped:        make(chan struct{}),
+		servingChanges: make(chan bool, 1),
+		blockGraceful:  blockGraceful,
+		forcedStop:     make(chan struct{}, 1),
+	}
+}
+
+func (server *fakeGRPCServer) Serve(net.Listener) error {
+	<-server.stopped
+	return grpc.ErrServerStopped
+}
+
+func (server *fakeGRPCServer) GracefulStop() {
+	if server.blockGraceful {
+		<-server.stopped
+		return
+	}
+	server.stopOnce.Do(func() { close(server.stopped) })
+}
+
+func (server *fakeGRPCServer) Stop() {
+	server.stopOnce.Do(func() { close(server.stopped) })
+	server.forcedStop <- struct{}{}
+}
+
+func (server *fakeGRPCServer) SetServing(serving bool) {
+	server.servingChanges <- serving
+}
+
+func TestNewHTTPServerAppliesTimeouts(t *testing.T) {
+	server := NewHTTPServer(config.Config{
+		Service: config.ServiceConfig{HTTPPort: "8080"},
+		Server: config.ServerConfig{
+			ReadTimeoutSeconds:       1,
+			ReadHeaderTimeoutSeconds: 2,
+			WriteTimeoutSeconds:      3,
+			IdleTimeoutSeconds:       4,
+		},
+	}, http.NewServeMux())
+
+	if server.ReadTimeout != time.Second || server.ReadHeaderTimeout != 2*time.Second {
+		t.Fatalf("unexpected read timeouts: %s, %s", server.ReadTimeout, server.ReadHeaderTimeout)
+	}
+	if server.WriteTimeout != 3*time.Second || server.IdleTimeout != 4*time.Second {
+		t.Fatalf("unexpected connection timeouts: %s, %s", server.WriteTimeout, server.IdleTimeout)
+	}
+}
+
+func TestServeMarksGRPCNotServingBeforeGracefulStop(t *testing.T) {
+	httpListener, grpcListener := testListeners(t)
+	grpcServer := newFakeGRPCServer(false)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	if err := Serve(
+		ctx,
+		&http.Server{Handler: http.NewServeMux()},
+		httpListener,
+		grpcServer,
+		grpcListener,
+		time.Second,
+	); err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case serving := <-grpcServer.servingChanges:
+		if serving {
+			t.Fatal("expected gRPC health to switch to NOT_SERVING")
+		}
+	default:
+		t.Fatal("expected a gRPC health status update")
+	}
+}
+
+func TestServeForcesGRPCStopAfterTimeout(t *testing.T) {
+	httpListener, grpcListener := testListeners(t)
+	grpcServer := newFakeGRPCServer(true)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := Serve(
+		ctx,
+		&http.Server{Handler: http.NewServeMux()},
+		httpListener,
+		grpcServer,
+		grpcListener,
+		25*time.Millisecond,
+	)
+	if err == nil {
+		t.Fatal("expected the shutdown deadline to be reported")
+	}
+
+	select {
+	case <-grpcServer.forcedStop:
+	default:
+		t.Fatal("expected gRPC Stop after the graceful shutdown deadline")
+	}
+}
+
+func testListeners(t *testing.T) (net.Listener, net.Listener) {
+	t.Helper()
+	httpListener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	grpcListener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		_ = httpListener.Close()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		_ = httpListener.Close()
+		_ = grpcListener.Close()
+	})
+	return httpListener, grpcListener
+}

biucingcli/template_data/microservice/template/internal/service/health.go

@@ -0,0 +1,26 @@
+package service
+
+import "{{MODULE_NAME}}/internal/model"
+
+type HealthService struct {
+	serviceName string
+	grpcPort    string
+	storeDriver string
+}
+
+func NewHealthService(serviceName string, grpcPort string, storeDriver string) HealthService {
+	return HealthService{
+		serviceName: serviceName,
+		grpcPort:    grpcPort,
+		storeDriver: storeDriver,
+	}
+}
+
+func (service HealthService) Status() model.HealthResponse {
+	return model.HealthResponse{
+		Service:  service.serviceName,
+		Status:   "ok",
+		Store:    service.storeDriver,
+		GRPCPort: service.grpcPort,
+	}
+}

biucingcli/template_data/microservice/template/internal/service/ping.go

@@ -0,0 +1,23 @@
+package service
+
+import "{{MODULE_NAME}}/internal/model"
+
+type PingService struct {
+	serviceName  string
+	protoPackage string
+}
+
+func NewPingService(serviceName string, protoPackage string) PingService {
+	return PingService{
+		serviceName:  serviceName,
+		protoPackage: protoPackage,
+	}
+}
+
+func (service PingService) Ping() model.PingResponse {
+	return model.PingResponse{
+		Message:      "pong",
+		Service:      service.serviceName,
+		ProtoPackage: service.protoPackage,
+	}
+}

biucingcli/template_data/microservice/template/internal/telemetry/telemetry.go

@@ -0,0 +1,56 @@
+package telemetry
+
+import (
+	"context"
+	"strings"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
+)
+
+func Setup(
+	ctx context.Context,
+	serviceName string,
+	endpoint string,
+) (func(context.Context) error, error) {
+	resourceAttributes := resource.NewWithAttributes(
+		semconv.SchemaURL,
+		semconv.ServiceName(serviceName),
+	)
+
+	options := []sdktrace.TracerProviderOption{
+		sdktrace.WithResource(resourceAttributes),
+	}
+
+	var setupErr error
+	if endpoint != "" {
+		exporterOptions := []otlptracehttp.Option{
+			otlptracehttp.WithEndpointURL(endpoint),
+		}
+		if strings.HasPrefix(endpoint, "http://") {
+			exporterOptions = append(exporterOptions, otlptracehttp.WithInsecure())
+		}
+
+		exporter, err := otlptracehttp.New(ctx, exporterOptions...)
+		if err != nil {
+			setupErr = err
+		} else {
+			options = append(options, sdktrace.WithBatcher(exporter))
+		}
+	}
+
+	provider := sdktrace.NewTracerProvider(options...)
+	otel.SetTracerProvider(provider)
+	otel.SetTextMapPropagator(
+		propagation.NewCompositeTextMapPropagator(
+			propagation.TraceContext{},
+			propagation.Baggage{},
+		),
+	)
+
+	return provider.Shutdown, setupErr
+}

biucingcli/template_data/microservice/template/internal/transport/grpc.go

@@ -0,0 +1,51 @@
+package transport
+
+import (
+	"net"
+
+	servicev1 "{{MODULE_NAME}}/api/gen/go/service/v1"
+	"{{MODULE_NAME}}/internal/service"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/health"
+	healthpb "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/reflection"
+)
+
+type GRPCServer struct {
+	server      *grpc.Server
+	health      *health.Server
+	serviceName string
+}
+
+func NewGRPCServer(serviceName string, pingService service.PingService) *GRPCServer {
+	server := grpc.NewServer()
+	healthServer := health.NewServer()
+	healthServer.SetServingStatus(serviceName, healthpb.HealthCheckResponse_SERVING)
+	healthServer.SetServingStatus("", healthpb.HealthCheckResponse_SERVING)
+	healthpb.RegisterHealthServer(server, healthServer)
+	servicev1.Register{{SERVICE_TYPE_NAME}}ServiceServer(server, newPingServer(pingService))
+	reflection.Register(server)
+	return &GRPCServer{server: server, health: healthServer, serviceName: serviceName}
+}
+
+func (server *GRPCServer) Serve(listener net.Listener) error {
+	return server.server.Serve(listener)
+}
+
+func (server *GRPCServer) GracefulStop() {
+	server.server.GracefulStop()
+}
+
+func (server *GRPCServer) Stop() {
+	server.server.Stop()
+}
+
+func (server *GRPCServer) SetServing(serving bool) {
+	status := healthpb.HealthCheckResponse_NOT_SERVING
+	if serving {
+		status = healthpb.HealthCheckResponse_SERVING
+	}
+	server.health.SetServingStatus(server.serviceName, status)
+	server.health.SetServingStatus("", status)
+}

biucingcli/template_data/microservice/template/internal/transport/ping.go

@@ -0,0 +1,28 @@
+package transport
+
+import (
+	"context"
+
+	servicev1 "{{MODULE_NAME}}/api/gen/go/service/v1"
+	"{{MODULE_NAME}}/internal/service"
+)
+
+type pingServer struct {
+	servicev1.Unimplemented{{SERVICE_TYPE_NAME}}ServiceServer
+	service service.PingService
+}
+
+func newPingServer(pingService service.PingService) *pingServer {
+	return &pingServer{service: pingService}
+}
+
+func (server *pingServer) Ping(
+	_ context.Context,
+	_ *servicev1.PingRequest,
+) (*servicev1.PingResponse, error) {
+	response := server.service.Ping()
+	return &servicev1.PingResponse{
+		Message: response.Message,
+		Service: response.Service,
+	}, nil
+}

biucingcli/template_data/microservice/template/scripts/bootstrap

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v brew >/dev/null 2>&1; then
+  brew bundle
+else
+  echo "brew not found; skipping Brewfile install."
+fi
+
+if command -v mise >/dev/null 2>&1; then
+  mise install
+else
+  echo "mise not found; skipping runtime install."
+fi
+
+if ! command -v go >/dev/null 2>&1; then
+  echo "go is not available on PATH."
+  echo "Install Go with Homebrew or activate it through mise, then rerun ./scripts/bootstrap."
+  exit 1
+fi
+
+if ! command -v buf >/dev/null 2>&1; then
+  echo "buf is not available on PATH."
+  echo "Install Buf with Homebrew or activate it through mise, then rerun ./scripts/bootstrap."
+  exit 1
+fi
+
+go mod tidy
+./scripts/doctor

biucingcli/template_data/microservice/template/scripts/doctor

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v go >/dev/null 2>&1; then
+  echo "go is not installed or not on PATH."
+  exit 1
+fi
+
+if ! command -v buf >/dev/null 2>&1; then
+  echo "buf is not installed or not on PATH."
+  exit 1
+fi
+
+go_version="$(go env GOVERSION)"
+echo "Go toolchain: $go_version"
+echo "Buf: available"
+
+if [[ -z "${GOCACHE:-}" ]]; then
+  GOCACHE="$(pwd)/.cache/go-build"
+  export GOCACHE
+fi
+mkdir -p "$GOCACHE"
+
+if [[ ! -f "./go.mod" ]]; then
+  echo "go.mod is missing."
+  exit 1
+fi
+
+if [[ ! -f "./configs/config.yaml" ]]; then
+  echo "configs/config.yaml is missing."
+  exit 1
+fi
+
+if [[ ! -f "./api/buf.yaml" ]]; then
+  echo "api/buf.yaml is missing."
+  exit 1
+fi
+
+if [[ ! -f "./api/buf.gen.yaml" ]]; then
+  echo "api/buf.gen.yaml is missing."
+  exit 1
+fi
+
+if [[ ! -f "./api/proto/service/v1/service.proto" ]]; then
+  echo "api/proto/service/v1/service.proto is missing."
+  exit 1
+fi
+
+if ! grep -q "name:" ./configs/config.yaml; then
+  echo "configs/config.yaml must define service.name."
+  exit 1
+fi
+
+if ! grep -q "http_port:" ./configs/config.yaml; then
+  echo "configs/config.yaml must define service.http_port."
+  exit 1
+fi
+
+if ! grep -q "grpc_port:" ./configs/config.yaml; then
+  echo "configs/config.yaml must define service.grpc_port."
+  exit 1
+fi
+
+service_name="$(sed -n 's/^  name: //p' ./configs/config.yaml | head -n 1)"
+http_port="$(sed -n 's/^  http_port: //p' ./configs/config.yaml | head -n 1)"
+grpc_port="$(sed -n 's/^  grpc_port: //p' ./configs/config.yaml | head -n 1)"
+
+if [[ -z "$service_name" ]]; then
+  echo "configs/config.yaml service.name must not be empty."
+  exit 1
+fi
+
+if [[ ! "$http_port" =~ ^[0-9]+$ ]]; then
+  echo "configs/config.yaml service.http_port must be a numeric string."
+  exit 1
+fi
+
+if [[ ! "$grpc_port" =~ ^[0-9]+$ ]]; then
+  echo "configs/config.yaml service.grpc_port must be a numeric string."
+  exit 1
+fi
+
+if (( http_port < 1 || http_port > 65535 )); then
+  echo "configs/config.yaml service.http_port must be between 1 and 65535."
+  exit 1
+fi
+
+if (( grpc_port < 1 || grpc_port > 65535 )); then
+  echo "configs/config.yaml service.grpc_port must be between 1 and 65535."
+  exit 1
+fi
+
+if ! go list -m >/dev/null 2>&1; then
+  echo "go.mod does not define a valid module."
+  exit 1
+fi
+
+if ! CONFIG_FILE=./configs/config.yaml go test ./internal/config -run TestLoadDefaultConfig -count=1 >/dev/null; then
+  echo "config loader could not read configs/config.yaml successfully."
+  exit 1
+fi
+
+if command -v golangci-lint >/dev/null 2>&1; then
+  echo "golangci-lint: available"
+else
+  echo "golangci-lint: not installed; make lint and make verify will be unavailable."
+fi
+
+if command -v docker >/dev/null 2>&1; then
+  echo "Docker: available"
+else
+  echo "Docker: not installed; compose workflows will be unavailable."
+fi
+
+echo "Environment looks ready."