zfoo is an Apache-2.0 licensed Java server framework for RPC, game servers and web servers, aimed at teams that need very high throughput and want to keep server configuration small and simple.

What it is

zfoo is a Java framework that describes itself as extremely fast, asynchronous, actor-designed, lock-free and universal, with native GraalVM support. It lives in the JVM ecosystem and, according to its topic list, is built around Netty for networking and MongoDB for persistence, with byte-buddy and javassist present for code manipulation. It is presented both as a game server framework and as a website server framework, and it scales from a single server deployment through microservice, cluster and gateway deployments.

The concrete problem it solves is the volume of plumbing that normally has to be written by hand around a high-performance service. Rather than assembling serialization, a cross-language wire protocol, an RPC layer, a MongoDB mapping layer, configuration parsing, an event bus, a scheduler and monitoring from separate sources, zfoo offers them as modules of one framework with a deliberately lightweight surface. Its own documentation states that the MongoDB ORM removes the need to write SQL or any configuration, and that CPU, memory, hard disk and network monitoring are built into the program with no code and no extra tools required. Hot code updates and hot configuration swaps are handled in the same package, so a running server does not have to be stopped for either.

Key capabilities

• A universal RPC framework over tcp, udp, websocket and http, where a method annotated with @PacketReceiver is registered automatically and consumers call NetContext.getCosumer().syncAsk(...) or .asyncAsk(...).
• Serialization through ProtocolManager.initProtocol(...), ProtocolManager.write(...) and ProtocolManager.read(...), with the zfoo protocol supporting C++, Rust, Java/Kotlin/Scala, JavaScript/TypeScript/ES, C#, Go, Php, Ruby, Lua, GDScript, Python, Dart and Swift.
• Hot update of code without downtime through a single call, HotSwapUtils.hotswapClass(bytes), with no additional configuration required.
• Excel, json and csv configuration files that are automatically mapped and parsed, with online hotswap of that configuration through the storage module.
• A MongoDB automapping framework in the orm module, where tables are defined without writing SQL or configuration by hand.
• An event bus and a time task scheduler, each available as its own module.
• CPU, memory, hard disk and network monitoring built into the program, plus native GraalVM support alongside OpenJDK and Oracle JDK.

Who uses it and how

• Projects with extremely high performance requirements: website and game server frameworks, single-server and global-server deployments, live chat, IM systems and real-time push.
• Teams trying to reduce development, deployment and operation and maintenance costs, following the project's stated Keep It Simple and Stupid approach to configuration.
• Game and web backends for Godot, Unity, Cocos, WebGL and H5 clients, with transport over tcp, udp, websocket or http.
• Existing Spring projects, distributed projects and container projects that want to ship hot code updates without taking the service down.
• Client-side developers using the published SDKs for C# and Lua on Unity and Godot, TypeScript and JavaScript on Cocos and web/H5, and GDScript on Godot, with the godot-bird sample as a reference.

Getting started

The environment requirement is JDK 17 or later, supporting OpenJDK, Oracle JDK and native GraalVM. Add the Maven dependency com.zfoo:boot:4.1.4, or depend on a single module such as com.zfoo:protocol:4.1.4, and use the runnable demos in the test folder of each module directory together with the FAQ.

How it compares

The facts provided name no paid or commercial products that zfoo replaces, and no competing framework is named either, so within this registry zfoo stands alone. The other tools it references are building blocks rather than rivals: Netty appears in the topic list as the networking layer, MongoDB as the backing store for the ORM, and GraalVM as a supported runtime beside OpenJDK and Oracle JDK.

When to use it — and when not to

A self-hoster operates a JVM service on JDK 17 or later and, if the orm module is used, a MongoDB instance, while the built-in monitoring removes the need for a separate monitoring stack. Teams that cannot move to JDK 17 or that want a non-Java stack should not pick it. The repository README is bilingual and the excerpt available here is truncated partway through the tutorial, so details of individual modules have to be taken from the per-module README files and the FAQ.

<dependency>
    <groupId>com.zfoo</groupId>
    <artifactId>boot</artifactId>
    <version>4.1.4</version>
</dependency>

<dependency>
    <groupId>com.zfoo</groupId>
    <artifactId>protocol</artifactId>
    <version>4.1.4</version>
</dependency>

// protocol registration
ProtocolManager.initProtocol(Set.of(ComplexObject.class, ObjectA.class, ObjectB.class));

// serialization
ProtocolManager.write(byteBuf, complexObject);

// deserialization
var packet = ProtocolManager.read(byteBuf);

// Service provider, only need to add an annotation to the method, the interface will be automatically registered
@PacketReceiver
public void atUserInfoAsk(Session session, UserInfoAsk ask) {
}

// Consumers, synchronously requesting remote service, will block the current thread
var ask = UserInfoAsk.valueOf(userId);
var answer = NetContext.getCosumer().syncAsk(ask, UserInfoAnswer.class, userId).packet();

// Consumers, asynchronously requesting remote service, and will still execute logic in the current thread after the asynchronous
NetContext.getCosumer().asyncAsk(ask, UserInfoAnswer.class, userId)
          .whenComplete(answer -> {
              // do something
          );

// Pass in the class file that needs to be updated
HotSwapUtils.hotswapClass(bytes);

// You don't need to write sql and any configuration yourself, define a table in the database directly through annotation definitions
@EntityCache
public class UserEntity implements IEntity<Long> {
    @Id
    private long id;
    private String name;
}

// update database data
entityCaches.update(userEntity);

// To receive an event, you only need to add an annotation to the method and the method will be automatically listen for the event
@EventReceiver
public void onMyNoticeEvent(MyNoticeEvent event) {
    // do something
}

// fire an event
EventBus.post(MyNoticeEvent.valueOf("My event"));

@Scheduler(cron = "0/1 * * * * ?")
public void cronSchedulerPerSecond() {
    // do something
}

@Storage
public class StudentResource {
    @Id
    private int id;
    @Index
    private String name;
    private int age;
}