hydra packs six server types and the plumbing around them into one Go container

Six server types in one process

hydra is described as a simple, unified and extensible service container framework for Go, and the description of the payload is the key to the design. With a small amount of integration code you get cluster management, configuration management, service registration and discovery, system monitoring, log collection, distributed tracing, secure access and a set of common components.

The six service types are API, WEB, WEBSOCKET, RPC, scheduled tasks and message consumption, and the README is explicit that they can be combined within a single application. The topics list gives the same set as api-server, webserver, websocket, rpcserver, cron, cronjob and mq-consumer.

The API server example is the shortest possible illustration of the model. You create an app with hydra.NewApp, naming the platform, the system or application, and the server types, then register handlers and start:

package main

import (
    "github.com/micro-plat/hydra"
    "github.com/micro-plat/hydra/hydra/servers/http"
)

func main() {
	app := hydra.NewApp(
            hydra.WithServerTypes(http.API),
    )
    app.API("/hello", func(ctx hydra.IContext) interface{} {
        return "hello world"
    })
    app.Start()
}

The RPC server is the same shape with rpc.RPC and app.RPC, the cron server uses cron.CRON with a schedule string, and the message consumer uses mqc.MQC with a queue name.

The platform names, system names and cluster names can be set as options at construction or supplied at run time as command line arguments, which is what makes the same binary deployable to several environments. The deployment modes are distributed cluster, single machine pseudo-cluster and single machine, and the cluster topologies offered are peer, sharded and master-slave.

The framework is cross-platform in the sense that it installs, runs, stops and uninstalls as a service on Windows, macOS and Linux.

Configuration from a centre, changed without a restart

The configuration model is the piece that most affects how an application behaves in production.

hydra uses a configuration centre, with configuration managed centrally and no local configuration to maintain. The supported sources are zookeeper, redis, local files and in-process configuration management. The in-process option is the escape hatch for a standalone run, and the others are what you use when several instances of the same service need to agree.

The second capability is hot update. After a configuration change takes effect automatically, there is no need to restart the service. For a platform whose stated purpose includes cluster management and configuration management, that is the feature that decides whether a change is a rolling operation or a restart window.

The per-server configuration is set through the same hydra.Conf accessor. The API listening port is set with a single call, and the read and request timeouts are options on it:

hydra.Conf.API("8090", api.WithHeaderReadTimeout(30), api.WithTimeout(30, 30))

Access control sits on the same object. A whitelist and a blacklist are configured by path pattern and by IP, and the JWT layer takes excludes and a header option, which is how a public login route is exempted while the token is carried in a header rather than a cookie.

    hydra.Conf.API("8080").
    WhiteList(whitelist.NewIPList("/**", whitelist.WithIP("192.168.4.121"))).
    BlackList(blacklist.WithIP("192.168.4.120"))

    hydra.Conf.API("8080").Jwt(jwt.WithExcludes("/member/**"), jwt.WithHeader())

The user information itself is carried on the context, with an auth response helper to set the token after login and a bind helper to read it back, which keeps the JWT plumbing out of the handler bodies.

Registry, metrics, tracing and log shipping

The observability and service-discovery features are the parts that make hydra a platform rather than a set of server helpers.

For registration and discovery, zookeeper, etcd and redis are supported as registry centres, and the registration exists to provide service management for remote calls, which is what a service registry is for in an RPC or HTTP world.

Business monitoring is metric based. Metric information such as QPS, processing duration and response is reported to influxdb on a schedule, so that the system can be watched on a dashboard for its operating condition. The reporting is periodic rather than streaming, which is the usual trade for a system that does not want to block a request on a metrics write.

Tracing is done with APM tools, with SkyWalking and Cat named, for distributed tracing, performance metric analysis, and application and service dependency analysis. The go.mod carries the SkyWalking agent for Go as a dependency, which confirms that the integration is at the library level rather than a manual instrumentation exercise.

Log collection is a separate delivery path. Local logs can be submitted to a log collection server, and the README links a project called rlog for that purpose, used for centralised log search and analysis. The choice of a dedicated log server rather than a shared one is consistent with the rest of the design, where each concern has a component the framework expects to exist.

On top of that sit access control, server rate limiting with degradation and circuit breaking, and a set of common component libraries: redis, memcached, databases, mqtt, activeMQ, rpc, uuid, distributed locks, an http client and an rpc client.

Gray release by script, with Tengo as the scripting language

The gray release feature is the most distinctive part of the framework and the one that most clearly states its intent.

You write a gray release script according to business rules, and the framework uses it to forward user requests to different clusters. The example given routes requests from IP addresses starting with 202.222. to a cluster whose name contains gray, and the script is written in Tengo:

	hydra.Conf.API("8090").Proxy(`
                request := import("request")
                app := import("app")
                text := import("text")
                types :=import("types")
                fmt := import("fmt")

                getUpCluster := func(){
                    ip := request.getClientIP()

The script gets access to the request, to information about the current application and cluster, and to standard formatting helpers, and it returns the target cluster. That is a real programmable routing layer, and Tengo is a small scripting language the framework embeds for exactly this purpose, visible in the dependency list as the d5/tengo module.

The trade is that you own a small scripting surface inside your request path. A routing script that throws, or that returns an unexpected cluster, is a production incident, and the framework gives you the primitives for the common case without giving you a type system or a test harness for the script itself.

The same configurability appears elsewhere, which is the general shape of the project: the platform and system and cluster names, the ports, the timeouts, the whitelists and blacklists, the JWT settings and the gray routing are all runtime configuration rather than compile time decisions.

Combining a cron server with an API server in one binary

The combined server example shows the payoff of the design, and it is a single process with two server types in it:

package main

import (
    "github.com/micro-plat/hydra"
     "github.com/micro-plat/hydra/hydra/servers/http"
     "github.com/micro-plat/hydra/hydra/servers/cron"
)

func main() {

	app := hydra.NewApp(
            hydra.WithServerTypes(http.API,cron.CRON),
    )

    app.API("/hello",hello)
    app.CRON("/hello",hello,"@every 5s") 
    app.Start()
}

The cron schedule is a cron expression, and the handler signature is the same hydra.IContext one the HTTP handlers use, so a scheduled job and an HTTP endpoint can share the same function.

The application is then started from the command line with the platform name as an argument:

$ ./flowserver run --plat test

and the resulting service is reachable over HTTP, which the README demonstrates with a request that returns the handler's string:

$ curl http://192.168.4.121:8080/hello

hello world

The message consumer server works the same way, with the queue implementation selected through the configuration, for example the local in-memory queue, with redis and mqtt also supported.

One design note for anyone writing a service: the same handler function can be registered on several server types, which is what the combined example demonstrates, and it is the clearest argument for the platform shape, since a small internal service often needs an endpoint for its callers and a schedule for its own housekeeping, and this gives you both without two deployments.

Dependencies, licensing and where hydra fits

The go.mod is a good map of the platform's ambitions. It requires Go 1.22 with a toolchain of go1.23.1, and the direct dependencies include the gin web framework, gorilla websocket, google.golang.org/grpc for RPC, IBM sarama for Kafka, the Eclipse Paho MQTT client, robfig/cron for the scheduler, the SkyWalking agent for Go, the Redis client, go-sql-driver/mysql, urfave/cli for the command line, promptui for interactive prompts, and the d5/tengo scripting engine. The micro-plat organisation also contributes its own gmq message queue and lib4go utility library.

That is a large dependency surface for a framework, and it is the honest cost of the platform shape. You are not picking a web framework, you are picking a web framework plus a scheduler, a message queue client, a tracing agent, a scripting engine, a registry client set and a configuration client set.

The repository layout follows the same shape, with app.go, dev.go, global.go and options.go at the root, and hydra/, conf/, components/, context/, creator/, registry/, services/, pkgs/, mock/, docs/ and a vendor/ directory alongside them. The vendor directory means the dependencies are committed, so a build does not have to reach the network for them.

The maintenance facts are worth stating precisely. The last push was on 2026-10-16 and the repository is not archived, so work is continuing, and the README states that the framework has been applied in more than 50 production projects. There are no GitHub releases, and the repository licence is not stated, which is the one gap a team adopting it should close first, since the framework is a dependency of every service that uses it. The documentation is in Chinese, which is the other practical barrier for adoption outside that ecosystem.

Editorial conclusion

hydra suits a team that wants one binary to be an API service, a scheduled worker and a message consumer at the same time, and that would rather take the configuration, registry and tracing conventions as they come than assemble them from separate libraries. It is the wrong choice for a service with one job, and for a team outside the Chinese ecosystem, since the documentation and the examples are in Chinese. Verify first that the configuration sources you need exist, in particular a registry your infrastructure already runs, and that the gray release scripting with Tengo is something you want to own, then read the module dependency list before you adopt the whole platform, because the framework pulls in Kafka, MQTT, SkyWalking, gRPC and an in-memory message queue at once.

Frequently asked questions

Official sources

1. Issues
2. micro-plat/hydra on GitHub
3. README