microservice_app

Microservice-oriented application kit for modern C++.

microservice_app provides a structured microservice base built on top of vix/service_app.

It enables:

• Microservice identity
• Internal service endpoints
• Peer service registry
• Internal request headers
• Service-to-service conventions
• Deterministic microservice structure

Header-only. Layered. Explicit.

Download

https://vixcpp.com/registry/pkg/vix/microservice_app

Why microservice_app?

Modern distributed systems are built from many small services.

Each service must manage:

• Internal service identity
• Communication with peer services
• Environment and deployment metadata
• Consistent internal endpoints
• Reliable service infrastructure

In many C++ systems these concerns are:

• Reimplemented for every service
• Mixed with application logic
• Inconsistent between services
• Hard to standardize across teams

microservice_app provides:

• A consistent microservice structure
• Internal communication conventions
• Peer service registry
• Standard internal endpoints
• Deterministic microservice identity

No service mesh required. No external framework required. No hidden runtime behavior.

Just a clean microservice foundation.

Dependency

microservice_app depends on:

• vix/service_app
• (transitively) vix/api_app
• (transitively) vix/web_app
• (transitively) vix/app

Architecture layering:

vix/app
  ↑
vix/web_app
  ↑
vix/api_app
  ↑
vix/service_app
  ↑
vix/microservice_app

This ensures:

• Clear service architecture
• Stable infrastructure layers
• Deterministic microservice behavior
• Minimal dependencies

Dependencies are installed automatically via Vix Registry.

Installation

Using Vix Registry

vix add vix/microservice_app
vix deps

Manual

git clone https://github.com/vixcpp/microservice_app.git

Add the include/ directory and ensure dependencies are available.

Core concepts

Microservice identity

Every microservice exposes structured metadata:

MicroserviceInfo info;
info.service = "orders";
info.version = "1.0.0";
info.environment = "production";
info.instance_id = "orders-1";

app.set_microservice_info(info);

This identity is used to:

• expose metadata
• build internal headers
• identify service instances

Peer services

Microservices often call other internal services:

app.add_peer("users", "http://users.internal");
app.add_peer("payments", "http://payments.internal");

Peers can then be queried:

auto url = app.peer_base_url("users");

This provides a simple internal service registry.

Internal headers

Service-to-service calls typically include service metadata.

microservice_app can generate internal headers automatically:

auto headers = app.internal_headers();

Example headers:

• x-vix-service: orders
• x-vix-instance: orders-1
• x-vix-env: production
• x-vix-version: 1.0.0

These headers help identify the calling service.

Internal endpoints

microservice_app exposes internal operational endpoints:

Endpoint	Purpose
/_internal/ping	basic service ping
/_internal/info	microservice metadata
/_internal/peers	peer registry

Example:

Request req;
req.method = HttpMethod::Get;
req.path = "/_internal/ping";

auto res = app.dispatch_service(req);

Internal requests

Internal requests can be created easily:

auto req = app.make_internal_request(
    HttpMethod::Get,
    "/_internal/ping"
);

This automatically attaches internal headers.

Standard endpoints

microservice_app inherits all endpoints from service_app:

Endpoint	Purpose
/health	Liveness check
/ready	Readiness check
/info	Service metadata
/metrics	Metrics snapshot

Additional internal endpoints:

Endpoint	Purpose
/_internal/ping	service ping
/_internal/info	microservice metadata
/_internal/peers	peer services

Main microservice flow

Typical microservice execution:

1. Configure microservice metadata
2. Register peer services
3. Register API routes
4. Register microservice routes
5. Run startup hook
6. Start HTTP runtime
7. Handle requests
8. Shutdown gracefully

Example setup:

MicroserviceApp app;

MicroserviceInfo info;
info.service = "orders";
info.version = "1.0.0";

app.set_microservice_info(info);

app.add_peer("users", "http://users.internal");

app.register_routes();

app.run_startup();

Complexity

Operation	Complexity
Peer lookup	O(1)
Health check evaluation	O(n)
Readiness check evaluation	O(n)
Metrics snapshot	O(1)
Request dispatch	depends on router

Peer lookups use a hash map for constant-time access.

Design philosophy

microservice_app focuses on:

• Deterministic microservice structure
• Explicit service identity
• Simple peer service wiring
• Lightweight service-to-service conventions
• Minimal runtime complexity

It does not attempt to replace:

• Service discovery systems
• API gateways
• Service meshes
• Distributed tracing platforms

Those belong to infrastructure layers outside the application.

Tests

Run:

vix build
vix test

Tests verify:

• microservice identity
• peer registry
• internal endpoints
• request dispatch
• service integration

License

MIT License
Copyright (c) Gaspard Kirira