mx

MX

A Go microservices framework with runtime launcher and services runner

Features

• Logger
• Launcher
• Services
• Services runner
• Enabler interface
• HealthChecker interface
• Metrics
• Health checker
• Liveness probe (/livez)
• Readiness probe (/readyz)
• Ping pong service
• Http transport
• GRPC transport
• GRPC client
• ConnectRPC transport
• ConnectRPC client

AI Agent Skills

This repository includes AI agent skills with documentation and usage examples for all packages. Install them with the skills CLI:

go install github.com/sxwebdev/skills/cmd/skills@latest
skills init
skills repo add tkcrm/mx

Launcher capabilities

How to use

Repo with example

Init launcher

var version = "local"
var appName = "mx-example"

logger := logger.New(
    logger.WithAppVersion(version),
    logger.WithAppName(appName),
)

ln := launcher.New(
    launcher.WithName(appName),
    launcher.WithLogger(logger),
    launcher.WithVersion(version),
    launcher.WithContext(context.Background()),
    launcher.WithAfterStart(func() error {
        logger.Infoln("app", appName, "was started")
        return nil
    }),
    launcher.WithAfterStop(func() error {
        logger.Infoln("app", appName, "was stopped")
        return nil
    }),
)

Init and register custom service

// init
svc := launcher.NewService(
    launcher.WithServiceName("test-service"),
    launcher.WithStart(func(_ context.Context) error {
        return nil
    }),
    launcher.WithStop(func(_ context.Context) error {
        time.Sleep(time.Second * 3)
        return nil
    }),
)

// register in launcher
ln.ServicesRunner().Register(svc)

Init and register ping pong service

import "github.com/tkcrm/mx/launcher/services/pingpong"

// init
pingPongSvc := launcher.NewService(launcher.WithService(pingpong.New(logger)))

// register in launcher
ln.ServicesRunner().Register(pingPongSvc)

Register any service that implements IService

Any struct with Name(), Start(), and Stop() methods satisfies types.IService and can be wrapped with launcher.NewService:

import "github.com/tkcrm/mx/launcher/types"

type books struct {
    name       string
    hcInterval time.Duration
}

func New() *books {
    return &books{
        name:       "books-service",
        hcInterval: time.Second * 3,
    }
}

func (s books) Name() string { return s.name }

func (s books) Healthy(ctx context.Context) error { return nil }

func (s books) Interval() time.Duration { return s.hcInterval }

func (s books) Start(ctx context.Context) error {
    <-ctx.Done()
    return nil
}

func (s books) Stop(ctx context.Context) error { return nil }

var _ types.HealthChecker = (*books)(nil)
var _ types.IService = (*books)(nil)

func main() {
    ln := launcher.New()

    // register service in launcher with health checker
    ln.ServicesRunner().Register(
        launcher.NewService(
            launcher.WithService(New()),
        ),
    )
}

Startup priority

Services can be assigned a startup priority to control initialization order. Services with the same priority start concurrently within a group. Groups are started sequentially in ascending priority order. Priority 0 (default) services start last, concurrently, after all prioritized groups are ready.

"Ready" is reported by the service itself: implement mxtypes.ReadinessReporter (Ready() <-chan struct{}, close the channel once operational) or pass WithReadiness(ch). A service that does not report readiness is considered ready as soon as its Start goroutine is launched — so a priority-1 database only truly blocks the next group if it reports readiness. WithStartupTimeout(d) bounds the wait for that signal.

ln.ServicesRunner().Register(
    // Priority 1: DB layer — start concurrently, both must be ready before next group
    launcher.NewService(
        launcher.WithServiceName("postgres"),
        launcher.WithStartupPriority(1),
        launcher.WithService(pgService),
    ),
    launcher.NewService(
        launcher.WithServiceName("redis"),
        launcher.WithStartupPriority(1),
        launcher.WithService(redisService),
    ),
    // Priority 2: message broker — waits for DB layer to be ready
    launcher.NewService(
        launcher.WithServiceName("rabbitmq"),
        launcher.WithStartupPriority(2),
        launcher.WithService(rabbitService),
    ),
    // Priority 0 (default): application services — start concurrently after all groups
    launcher.NewService(
        launcher.WithServiceName("http-server"),
        launcher.WithService(httpService),
    ),
    launcher.NewService(
        launcher.WithServiceName("grpc-server"),
        launcher.WithService(grpcService),
    ),
)
// Start order: (postgres + redis) → rabbitmq → (http + grpc concurrently)

Graceful shutdown

The first signal (SIGTERM / SIGINT / SIGQUIT) starts a graceful shutdown. A second signal forces immediate exit.

if err := ln.Run(); err != nil {
    logger.Fatal(err)
}