PHPackages                             hx/interop - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. hx/interop

ActiveLibrary[Utility & Helpers](/categories/utility)

hx/interop
==========

Make all the languages talk to each other

v0.5.0(3y ago)071Apache-2.0GoPHP ^8

Since Dec 3Pushed 3y ago1 watchersCompare

[ Source](https://github.com/hx/interop)[ Packagist](https://packagist.org/packages/hx/interop)[ RSS](/packages/hx-interop/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (1)Versions (12)Used By (0)

Interop
=======

[](#interop)

Layers of simple inter-process messaging goodness.

The Golang implementation is the reference for the other implementations.

Protocol
--------

[](#protocol)

Interop relies on the exchange of messages between processes. Messages are comprised of MIME-style headers, and bodies.

```
Content-Type: application/json
Content-Length: 14

{"foo":"bar"}

```

All headers are optional. A double line-break serves as a message terminator in the absense of a `Content-Length` header.

### RPC

[](#rpc)

In a client/server pairing, a client process can make an RPC request using an ID and a Class. IDs should be unique per session. Clients are responsible for generating IDs. Classes should tell servers how to handle requests.

```
Interop-Rpc-Class: ping
Interop-Rpc-Id: 1

Are you there?

```

The server should send a response with the same ID header.

```
Interop-Rpc-Id: 1

Yes I am!

```

Servers may send other messages before sending a response (including events and/or responses to other requests), so clients should wait for a message with the same ID.

Servers may send events to clients at any time. An event is simply a message without an ID. Events should have class headers that inform clients how they are to be handled.

Implementation principles
-------------------------

[](#implementation-principles)

### Messages

[](#messages)

The base type in each language is a `Message`, which should have `headers` and a `body`.

Headers are collections of MIME headers. They should be used in a case-insensitive way.

Bodies are raw binary, and therefore suitable for transmission of compressed data, video streams, etc.

### Readers/Writers

[](#readerswriters)

Each language has reader and writer interfaces, which wrap around native IO primitives to allow reading/writing messages directly to/from files (e.g. STDIN/STDOUT), sockets, pipes, buffers, etc.

### Connections

[](#connections)

A connection is the combination of a reader and a writer, and should represent a process's bidirectional interface; for example, STDIO, a TCP socket, or pipes into a subprocess.

### Pipes

[](#pipes)

A pipe simple allows you to read whatever messages are written to it. Pipes can block or have buffers, depending on implementation.

### Closing up

[](#closing-up)

Readers, writers, and connections generally can't be closed directly. Their underlying IO streams should be closed instead.

Pipes, however, do not represent IO primitives, and so can be closed directly.

### RPC

[](#rpc-1)

RPC servers and clients wrap around connections to provide core RPC (or any other request-response) functionality.

Clients can augment regular messages with the ID and Class headers required for RPC, and wait for servers to send responses to them, matching responses with requests by ID. Clients can also listen for specific classes of event send by servers, running handlers for them.

Servers can be configured to respond to specific classes of messages with different handlers, allowing responses to be seamlessly returned to clients.

Because clients and servers are both "listening" (clients for events, and servers for requests), they have blocking behaviours that are managed differently depending on available tooling. In most cases a process will be able to wait for a client or server to close or error out.

### Concurrency/parallelism

[](#concurrencyparallelism)

Readers and writers use mutexes to ensure they are only reading or writing one message at a time, regardless of how many threads are accessing them. As such, operations involving the movement of messages are generally thread-safe.

Client event handlers and server request handlers are generally processed asynchronously wherever possible, to minimise blocking on IO streams.

Examples
--------

[](#examples)

In the below examples, each language implements the same client/server combination.

Client and server processes talk to each other using two FIFOs called `a` and `b`. Clients write to `a` and read from `b`, and servers write to `b` and read from `a`.

Clients send a single RPC request, `countdown`, to servers, with a single header, `ticks`, as an integer. Servers respond to `countdown` by sending one `tick` event per second back to the client, up to the number in the request's `ticks` header.

Clients handle the `tick` event by writing `Tick n` to their STDOUT. After receiving their final tick, they close FIFO `a`, which causes the server to exit, which in turn causes the client to exit.

These examples are all runnable from the [examples](examples) directory.

### Go

[](#go)

#### Server

[](#server)

```
import (
    "github.com/hx/interop/interop"
    "os"
    "strconv"
    "time"
)

func main() {
    reader, _ := os.OpenFile("a", os.O_RDONLY, 0)
    writer, _ := os.OpenFile("b", os.O_WRONLY|os.O_SYNC, 0)

    server := interop.NewRpcServer(interop.BuildConn(reader, writer))

    server.HandleClassName("countdown", interop.ResponderFunc(func(request interop.Message, _ *interop.MessageBuilder) {
        num, _ := strconv.Atoi(request.GetHeader("ticks"))
        for i := 1; i on('countdown', function (Hx\Interop\Message $message) use($server) {
    $num = (int) $message['ticks'];
    for ($i = 1; $i send('tick', Hx\Interop\Message::json($i));
    }
});

$server->wait();
```

#### Client

[](#client-2)

```
$writer = fopen('a', 'w');
$reader = fopen('b', 'r');

$client = new Hx\Interop\RPC\Client($reader, $writer);

$client->on('tick', function (Hx\Interop\Message $message) use ($writer) {
    $num = json_decode($message->body);
    echo "Tick $num\n";
    if ($num === 5) {
        fclose($writer);
    }
});

$client->call('countdown', ['ticks' => 5]);

$client->wait();
```

### JavaScript

[](#javascript)

> TODO

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~113 days

Recently: every ~134 days

Total

8

Last Release

1195d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6d706bfbe40a02d6af38ae5cd2f8ac84af56476183b5eb4c926f9ff4b0f8052e?d=identicon)[hx](/maintainers/hx)

---

Top Contributors

[![hx](https://avatars.githubusercontent.com/u/692853?v=4)](https://github.com/hx "hx (86 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hx-interop/health.svg)

```
[![Health](https://phpackages.com/badges/hx-interop/health.svg)](https://phpackages.com/packages/hx-interop)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)