Skip to content

Installation and the First Connection

Contents | Previous: Stream Connector Overview | Next: Connector Options

View in another language — C++ · C#/.NET · Java · Kotlin · Node/TypeScript

After reading this chapter

You can add the connector package to a project, connect to a server, and exchange the first packet. The connection code in this chapter runs as it stands in framework/languages/java/tutorial/kotlin/StreamClient.

The connector ships separately from the server framework, so a client project references the connector package alone. This chapter walks from installation to the first reply. The full set of options and their defaults is covered by Connector Options.

1. Installation

dependencies {
    implementation("systems.zlink:zlink-stream-connector:0.30.0")
    // Coroutine wrapper. The surfaces that suspend with await() live in this module.
    implementation("systems.zlink:zlink-framework-kotlin:0.30.0")
}

2. Connecting and the First Request

A connector is created from options that carry the endpoint and the timeouts. Packets can be sent only after the connection is established, so the connection is awaited first. A request waits until the server's answer arrives and then returns the answer payload.

// A game client outside the mesh. It references the connector only, never the
// Framework, and speaks to the port the stream node opened.
val connector =
    ZLinkStreamConnectorFactory.create(
            ZLinkStreamConnectorOptions(
                URI.create("tcp://127.0.0.1:7621"),
                ZLinkStreamDispatchMode.IMMEDIATE,
                Duration.ofSeconds(5),
                1,
            )
        )
        .kotlin()

connector.connect().await()
println("connected: ${connector.isConnected}")

// A request waits for its reply. Use send for one-way traffic; the server
// then answers with client().send rather than reply.
val sentAt = System.currentTimeMillis()
val pong =
    connector.request<Pong>(Ping(sentAt.toString())).timeout(Duration.ofSeconds(5)).await()

println("round trip: ${System.currentTimeMillis() - pong.sentAtUnixMs.toLong()}ms")

A browser client connects over ws://

Native builds use tcp://, tls://, ws://, and wss://. A browser runtime cannot open an OS socket, so it uses ws:// or wss:// only, and the server endpoint carries the same scheme.

3. What You See

The command below runs the tutorial (framework/languages/java/tutorial/kotlin) StreamClient with its Server started as described in the README's "Run" section; StreamClient connects to the Server's stream endpoint.

dotnet run --project StreamClient/StreamClient.csproj
# connected: True
# round trip: 56ms

A true connected means the connection is established. The round trip is measured from the time the client sent, which the server echoes back.

4. Sending Without an Answer

A packet that needs no answer is sent with send. Nothing goes out until the terminal call is made, and that terminal reports completion and failure only. Use a request when the client needs to know what the server did.

// val connector = ZLinkStreamConnectorFactory.create(options).kotlin()
connector.send(ChatMessage("room-42", "hello"))
    .packetName("chat.send")   // Omitted, the name comes from the payload type.
    .await()

5. Receiving What the Server Sends First

Packets the server sends on its own are received by a registered handler. Registration returns a value that can be released, and the handler stays in place while that value lives. Under the default setting a handler does not run at receive time: it runs in the execution context that called the pump. A game loop calls the pump once per frame.

val subscription = connector.on<LeaderboardUpdate> { message ->
    println(message.payload.rank)
    CompletableFuture.completedFuture(null)
}

while (running) {
    connector.dispatch().await()   // Runs the handlers queued so far and returns.
    renderFrame()
}

6. Next Chapters