zre 0.1.0__tar.gz

zre-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-13
+
+### Added
+
+- Pure Python ZRE (ZeroMQ Realtime Exchange Protocol, RFC 36) implementation
+  built on asyncio + pyzmq — single event loop, no threads, no C extensions
+  beyond pyzmq.
+- Zero-configuration LAN peer discovery via UDP beacons (port 15670).
+- Direct peer dialing with `connect_peer(host, port)` across subnets/WAN,
+  including NAT port-forwarding via `set_advertised_endpoint()`.
+- Group messaging (`join`/`leave`/`shout`) and direct messaging (`whisper`).
+- Heartbeating with evasive/expired detection (`ENTER`/`EXIT`/`EVASIVE` events).
+- Custom headers exchanged during discovery via `set_header()` (`X-` headers).
+- Fixed ROUTER port (`set_beacon_peer_port`) and interface pinning
+  (`set_interface`) for repeatable deployments.
+- Wire-compatible with any RFC 36 peer: UDP beacon (`ZRE\x01` + UUID + port)
+  and `HELLO/WHISPER/SHOUT/JOIN/LEAVE/PING/PING_OK` with `0xAAA1`/v2/seq.
+- 65 tests covering LAN discovery, WAN direct connect, and protocol edge cases.
+- 17 validated examples: chat, service discovery, sensor network, file
+  transfer, media streaming, game sync, task queue, whiteboard, presence,
+  config sync, health monitor, distributed lock, secure chat, benchmark.
+
+[0.1.0]: https://github.com/pitch-cardinal-coding/zre/releases/tag/v0.1.0

zre-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail
+address, posting via an official social media account, or acting as an
+appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**theichux@gmail.com**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

zre-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to zre
+
+Thanks for your interest in contributing! This document covers the basics for
+getting a development environment running and submitting changes.
+
+## Development setup
+
+```bash
+# Create a virtualenv (any Python >= 3.9 works; tested on 3.14)
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install in editable mode with dev tools
+pip install -e .[dev]
+
+# Or install the pinned runtime/dev stack
+pip install -r requirements.txt
+pip install -e .
+```
+
+## Running tests and lint
+
+```bash
+make test      # pytest (65 tests)
+make lint      # ruff check zre tests examples
+make format    # ruff format
+make ci        # check-format + lint + test
+```
+
+Notes:
+
+- Tests use real UDP beacons on loopback (`127.255.255.255` / `127.0.0.1`),
+  so they work inside containers and CI without extra setup.
+- Tests need the ability to bind UDP ports and localhost TCP sockets.
+- The library imports `fcntl` at module load, so it targets POSIX (Linux,
+  macOS). Windows is not supported.
+
+## Pull requests
+
+1. Fork the repo and create a topic branch from `main`.
+2. Make your change. Add tests for anything behavioral — new protocol
+   handling, timers, or peer state transitions especially.
+3. Run `make ci` and make sure it passes.
+4. Keep the wire format untouched: `zre` speaks RFC 36 on the wire. If your
+   change would alter framing, sequencing, or beacon layout, open an issue
+   first to discuss it.
+5. Update `CHANGELOG.md` under an "Unreleased" heading.
+6. Open the PR with a short description of what changed and why.
+
+## Reporting bugs
+
+Open a [GitHub issue](https://github.com/pitch-cardinal-coding/zre/issues)
+with your Python version, OS, and a minimal reproduction (one of the
+`examples/` scripts usually works well). For security-sensitive reports, see
+[SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under
+the [MIT License](LICENSE).

zre-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chukwudi Nwachukwu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zre-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+# Include OSS/community docs in the source distribution
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include SECURITY.md
+include README.md
+
+# Tests ship with the sdist so downstream packagers can run them
+recursive-include tests *.py
+
+# Keep ruff config available (it lives in pyproject.toml, included by default)