Open source · Go · pre-1.0

Multi-protocol
services in Go.

Serve HTTP, TCP, WebSocket, QUIC, gRPC and other protocols in one Go application. KPro provides component assembly, message routing and lifecycle management.

Start learning Run locally Framework reference

A runnable project in 9 chapters · Tutorial in Chinese

Queue and concurrency limits Shared business logic Startup, readiness and shutdown

cmd/gateway/main.go ready

// Checked assembly catches invalid config early.
app, err := server.NewChecked(server.Config{
    Name: "gateway",
})
if err != nil { return err }

messages := app.Mount(tcp.New(tcp.Config{
    Addr:  ":9000",
    Codec: codec.KProV1(),
}))
messages.HandleSync(msgid.Echo, echo)

app.MountNative(httpEndpoint)

handle, err := app.Start(ctx)
if err != nil { return err }
return handle.Wait()

When KPro is useful

Several entry points, one application

KPro is useful when different clients need different protocols, while your business rules and service lifecycle belong together.

HTTP APIs and a TCP client

Expose HTTP endpoints for ordinary requests and a TCP message interface for a dedicated client. Both adapters can call the same business service, with listeners started and stopped together.

HTTP APIs and browser connections

Keep regular HTTP APIs alongside WebSocket connections. Reuse business services while defining the messages and connection behavior your application needs.

For a simple HTTP-only service, first consider whether you need component assembly and shared lifecycle management. Start with one protocol and add another when the product needs it.

A result you can verify

Create over HTTP. Read the same order over TCP.

The downloadable teaching project connects two protocol adapters to one order service and one store. Follow a single order through a state change.

01HTTP

Create an order

POST /orders

Send the JSON below. A successful request returns HTTP 201 and an order with its own id and pending status.

{"sku":"coffee","quantity":2}

02TCP

Query through TCP

go run ./cmd/ordercli -id ORDER_ID

Pass the returned id to the example client. It sends a framed query message and prints the same order in pending state.

03HTTP

Cancel over HTTP

POST /orders/ORDER_ID/cancel

Use the same id in the cancellation URL. The HTTP response returns the order with status changed to cancelled.

04TCP

Query again

go run ./cmd/ordercli -id ORDER_ID

Run the TCP client again with that id. It now reads cancelled from the same business service and store.

Start the downloaded project with its TCP listener enabled:

go run ./cmd/orders -db lesson.db -tcp 127.0.0.1:8088

Replace ORDER_ID with the id returned in step 1. Each TCP query reads the current state of that same order.

Walk through the HTTP + TCP example See how the objects are wired Download the runnable project

How to build your application

Separate protocol handling from business rules

In the order project, adapters translate requests, the service applies business rules, and the store saves state. These are application modules with explicit connections.

1. Protocol adapters

Parse HTTP JSON or a TCP message, call the service, then translate its result into the response expected by that client.

internal/httpapi/api.gointernal/messageapi/api.go

2. Business service

Validate order input and control state changes. The service does not need to know which protocol delivered the request.

internal/order/service.go

3. Storage contract

The application defines order.Store. Its memory and SQLite implementations provide the same operations for saving and reading orders.

internal/memory/store.gointernal/sqlite/store.go

The composition root creates one service and passes it to both adapters. Adding a protocol entry point does not require a second copy of the order business.

Read internal/app/app.go

KPro manages the mounted components

Validate configuration and coordinate startup, readiness and shutdown. Message protocols can also use Router dispatch and configured queue and concurrency limits.

Your application defines the product behavior

Define request and message contracts, business rules, authentication, authorization and idempotency. Choose the storage implementation and manage the resources it owns.

Change storage through an application interface

Memory: start with temporary data

The example stores orders in a process-local map. It is useful for early experiments and tests; stopping the process removes those orders.

go run ./cmd/orders -memory

SQLite: keep data in a local file

The example uses a SQLite file. Restart with the same database path to read previous orders. This teaching implementation uses one process and one database connection.

go run ./cmd/orders -db lesson.db

Both implementations satisfy the same application contract, so the business service stays unchanged. To add another database, implement and test that contract.

Follow the persistence chapter

Choose from your client needs

Start with the entry points your product needs

Start with a common combination, then adjust it for your clients. See what each protocol is used for and which handlers and request contracts you need to write.

Use the guidance below to understand the adapter work and request contracts needed for your selected protocols.

SELECTED ENTRY POINTS2 protocols

TCPHTTP / HTTP/2

TCP

Define message IDs and payloads, select a frame codec and call the same business service from the TCP adapter.

HTTP / HTTP/2

SHARED LIFECYCLE

Startup · Endpoint readiness · Shutdown

Running the application

Know when it is ready, and how it stops

A successful listener is only the start. Configure capacity for the relevant components, observe failures, and give shutdown a defined deadline.

Trace the runnable lifecycle example Read the operations reference

01
Validate, then start
Check configuration when creating and mounting components, then wait for managed endpoints to become ready. A return from Start alone does not confirm that every listener started successfully.
02
Check the dependencies you actually need
In the teaching app, /livez confirms an HTTP response, while /readyz calls the store health check and returns 200 or 503. The application implements these routes; WaitReady coordinates endpoint startup.
03
Set and observe capacity limits
Configure message-router queues and concurrency, plus the connection and pending-send limits supported by the chosen transport. Use component metrics and errors to see where requests are waiting or being rejected.
04
Wait for shutdown before closing storage
Cancellation triggers bounded shutdown and drain work. In the example, Wait completes before the application closes SQLite. Storage cleanup belongs to the application; draining a send queue is not a business-delivery guarantee.

Quick start

Install the CLI and create an HTTP service

Use the CLI to start a new HTTP project, then add your own routes and business logic. The order tutorial below is a separate, already implemented application.

Requires Go 1.26.9+. Run the three steps in order in your local terminal.

$ go install github.com/saramand9/kpro/cmd/kpro@v0.2.1

How to verify this step

After installation succeeds, run kpro version to view CLI build information. If the command is not found, add the Go executable installation directory to PATH.

KPro is pre-1.0. Pin an exact version and use the documentation for that release.

Want a complete example? Run and verify the order-service tutorial (Chinese) →

Prefer to explore a complete project first?

The order project already implements create, query and cancel operations, plus memory and SQLite storage. Download it to verify state changes and persistence before reading how it is assembled.

Download the order project

Version and adoption

This site targets KPro v0.2.1

KPro is pre-1.0 and its APIs are not frozen. Pin the release and use matching documentation. Before adopting it in a deployed service, test your actual protocol combination, workload and shutdown behavior.

API stability Production checklist Production v1 roadmap

Do I have to use several protocols?

No. Start with the HTTP entry point you need today. Mount another component when a client requirement justifies it, and decide which business services should be shared.

Does KPro replace routing and storage code?

KPro provides protocol components and dispatch mechanisms. You still register routes or messages, implement request contracts and business behavior, and choose and wire storage. It does not automatically turn an HTTP route into a TCP API.

Is the order example a finished business product?

It is a runnable teaching application, with explicit limits. It does not include accounts, payments, inventory or subscriptions. Use it to understand the structure, then design and test the requirements of your own product.

Multi-protocolservices in Go.