This release is a pre-release and may not be stable for production use.
Stinger IPC
StingerIPC provides inter-process communications (IPC) between a server and multiple clients running on the same or separate hosts. It uses an MQTT server to pass messages between processes, implementing several IPC patterns: signals, commands, properties, and proceedures.
Project Status
This project is in early stages of active development. You should not use it in any of your projects, both because it doesn't have enough features yet to be useful, and also because things will probably be horribly broken on future updates.
Interface Description
StingerIPC takes a interface description file (.singeripc), and will generate code and documentation from it. A very brief example of a interface description is:
stingeripc:
version: 0.3.0
interface:
name: Example
version: 0.0.1
signals:
foo:
values:
- name: message
type: string
methods:
addNumbers:
arguments:
- name: left
type: integer
- name: right
type: integer
returnValue:
name: sum
type: integer
properties:
favorite_number:
value:
name: number
type: integer
Command Line Interface
The stinger-ipc command provides two main subcommands for working with Stinger interface files:
Generate Code
Generate code from a Stinger interface YAML file:
uvx stinger-ipc generate INPUT_FILE OUTPUT_DIR [OPTIONS]
Arguments:
INPUT_FILE- Path to the.stinger.yamlinterface description fileOUTPUT_DIR- Directory where generated files will be written
Options:
-l, --language TEXT- Language to generate:rust,python,markdown,cpp,web,protobuf--template-pkg TEXT- Python package(s) containing custom templates (advanced)--template-path PATH- Filesystem path(s) to custom template directories (advanced)--consumer TEXT- Consumer name/identifier for filtering interface (advanced)--config PATH- TOML configuration file(s) - later files override earlier ones (can be specified multiple times)
Examples:
# Generate Python code
uvx stinger-ipc generate my_interface.stinger.yaml ./output --language python
Validate Interface
Validate a Stinger interface YAML file against the schema:
uvx stinger-ipc validate INPUT_FILE
First class code generation
From the StingerIPC description file, we directly generate server and client code for these languages: Python3, C++11, and Rust.
Server Code
From the above description file, StingerIPC generates server code, which can be used like this:
# Python
conn = MqttConnection('localhost', 1883)
server = ExampleServer(conn)
server.emit_foo("Hello World")
@server.handle_add_numbers
def add_numbers(left: int, right: int) -> int:
return left + right
// C++
auto conn = std::make_shared<DefaultConnection>("localhost", 1883);
ExampleServer server(conn);
server.emitFoo("Hello World").wait();
server.registerAddNumbersHandler([](int left, int right) -> int
{
return left + right;
});
// Rust
let connection = Connection::new(String::from("tcp://localhost:1883"));
let mut server = SignalOnlyServer::new(connection);
server.emit_foo("Hello World".to_string());
server.register_add_numbers_handler(|left, right| {
left + right
});
Client Code
From the above description file, StingerIPC generates client code which can be used like this:
# Python
conn = MqttConnection('localhost', 1883)
client = ExampleClient(conn)
@client.receive_foo
def print_foo_receipt(message):
print(f"Got a 'foo' signal with message: {message}")
future = client.add_numbers(1, 2)
timeout = 5
print(future.result(timeout))
// C++
auto conn = std::make_shared<DefaultConnection>("localhost", 1883);
ExampleClient client(conn);
client.registerFooCallback([](const std::string& message) {
std::cout << message << std::endl;
});
std::cout << "One plus three is " << client.addNumbers(1, 3).wait() << std::endl;
// Rust
let connection = Connection::new(String::from("tcp://localhost:1883"));
let mut client = ExampleClient::new(connection);
client.set_signal_recv_callbacks_for_foo(|message| {
println!("{}", message);
});
client.add_numbers(1, 4);
AsyncAPI and second-class code generation
AsyncAPI is a specification format for describing asynchronous message APIs. Since StingerIPC uses and abstracts asynchonous messages between server and clients, we can describe a StingerIPC system with an AsyncAPI document.
From that AsyncAPI document, we can generate code and documentation in additional languages. While this code generation won't implement our standard IPC design patterns, it does make accessing the communications more easy.
Inter-process communication (IPC)
The motivation for this project is that I've seen embedded Linux projects that run several daemons that need to talk to each other, and for whatever reasons D-Bus wasn't a good option.
So this project is a way for those daemons/programs to communicate with each other through an MQTT broker running on the same device. The design goals of this project have been tuned toward this use case.
That being said, there is nothing prohibiting Stinger-IPC to be used for RPC: remote proceedure calls. RPC typically involves being able to call into a system from a different system. That certainly can be done by having the remote systems connect into the same MQTT broker as the local system. However, this isn't the primary use case, and design goals aren't geared to make Stinger-IPC the best solution for RPC (though don't let that stop you from using it that way). Specifically, Stinger-IPC requires the server and all clients to be running the same version of code. For systems where all the software ships together, this usually isn't a problem, but could be a problem for systems with remote connections.
Comparison to gRPC
gRPC is probably a better solution for handling RPC and connections from remote clients. It does a much better job at handling compatibility between different versions, supporting a wider number of languages, and transports messages more efficiently.
But gRPC, as most typically deployed, provide some challenges for use inside an embedded Linux system. gRPC typically wants secured HTTP/2 connections, which are just overkill for communications within a single device. Additionally, the protobuf code generation is just more complicated.
Plugin System
The user can specify templates that override or add to the built-in templates. Those templates can come from a directory (use the --template-path command line flag) or from another package (use the template-pkg command line flag). When those templates need a way to extend the model system, it can add additional symbols by implementing the "stinger_symbols" entry point (see the pyproject.toml file for built-in examples on how to do this).
Design goals
- Low learning curve.
- No fancy/tricky code. Generated code should look like a a human wrote it for humans to use it.
- Useable for embedded Linux systems.
- Be described by an AsyncAPI spec.
License
Generator Code
The stinger-ipc generator (Python scripts, templates, and related files) is licensed under the MIT License. See the LICENSE file for details.
Generated Code
Code generated by stinger-ipc is NOT subject to the MIT License. As a special exception, you may use, modify, and distribute code generated by stinger-ipc under any license of your choosing, including proprietary licenses, without attribution or restriction.
This exception applies to all output produced by running the stinger-ipc code generator, regardless of the input files or configuration used. You are free to:
- Use generated code in commercial projects
- Relicense generated code under any terms
- Modify and distribute without attribution
- Include in proprietary software
The templates in stingeripc/templates/ automatically include a license notice in generated files to clarify this.
1 maintainer
Metadata
1 maintainer
Release files for stinger-ipc 0.11.2b1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stinger_ipc-0.11.2b1.tar.gz | 324.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stinger_ipc-0.11.2b1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 703.4 kB
Release files / stinger_ipc-0.11.2b1.tar.gz
| Download URL | stinger_ipc-0.11.2b1.tar.gz |
|---|---|
| Size | 324.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0a0b03b4b887ffd37a10331d9ec703659e95719f79fd9ef358f4ac2501e65aa3
|
|
BLAKE2b-256 checksum How to use checksums |
245b6febed0105d31604630bdb9b4139618b8e88e4241e5ae5b20a6bc1182b12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / stinger_ipc-0.11.2b1-py3-none-any.whl
| Download URL | stinger_ipc-0.11.2b1-py3-none-any.whl |
|---|---|
| Size | 379.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
71ba7fbf40306fb585a846f3996a86524ca59bcd7348086002027f5de4870c44
|
|
BLAKE2b-256 checksum How to use checksums |
a5190175294f985c537a7dde1815bcfac5c7ed22f4d2b6f200e355a73eec429c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
