pulsar-lite 0.1.0__tar.gz

pulsar_lite-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: pulsar-lite
+Version: 0.1.0
+Summary: Embedded Apache Pulsar-compatible broker for local development
+Author-email: Ascentstream <community@ascentstream.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ascentstream/pulsar-lite
+Project-URL: Documentation, https://github.com/ascentstream/pulsar-lite#readme
+Project-URL: Repository, https://github.com/ascentstream/pulsar-lite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pulsar-client>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# Pulsar Lite
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ascentstream/pulsar-lite/blob/main/LICENSE)
+
+Pulsar Lite is a lightweight local broker that implements the core Apache Pulsar
+binary protocol. This package ships a small Python helper that can start and
+manage a local broker process, so you can use Pulsar topic names and the
+official Pulsar Python client with a single local file path.
+
+It is designed for fast local feedback, not as a production replacement for an
+Apache Pulsar cluster. Use Apache Pulsar for production workloads that require
+multi-broker scheduling, replication, capacity management, tenant isolation, or
+operational SLAs.
+
+## Why use the Python helper
+
+Many applications only need a local broker to validate the messaging path:
+producers, consumers, subscriptions, flow control, failover, and key-based
+routing. Setting up a full Pulsar deployment can be more expensive than the
+test or prototype itself.
+
+`pulsar-lite` keeps the client-facing API close to Pulsar while removing the
+local setup cost:
+
+- Start a local broker by passing a file path, no manual process management.
+- Connect with the official `pulsar-client` (installed automatically).
+- Use Pulsar topic names such as `persistent://...` and `non-persistent://...`.
+- Exercise Shared, Failover, Exclusive, and KeyShared subscription behavior.
+
+## Installation
+
+```bash
+pip install pulsar-lite
+```
+
+The package declares `pulsar-client>=3.0.0` as a runtime dependency, so the
+official Pulsar Python client is installed automatically.
+
+Platform wheels include a prebuilt broker binary. If no wheel matches your
+platform, see the [build from source](#building-the-broker-from-source) section.
+
+## Quick start: embedded mode
+
+Pass a local file path and the helper starts a broker process for you:
+
+```python
+import pulsar
+from pulsar_lite import PulsarClient
+
+topic = "non-persistent://public/default/quick-start"
+
+with PulsarClient("./demo.db") as client:
+    consumer = client.subscribe(
+        topic,
+        "quick-start-sub",
+        consumer_type=pulsar.ConsumerType.Shared,
+    )
+    producer = client.create_producer(topic)
+
+    producer.send(b"hello from pulsar lite")
+    message = consumer.receive(timeout_millis=5000)
+    print(message.data().decode("utf-8"))
+    consumer.acknowledge(message)
+```
+
+When the `PulsarClient` context exits, the embedded broker process is stopped
+automatically (reference counted, so multiple clients on the same path share
+one broker).
+
+## Quick start: remote mode
+
+If you already have a broker running (locally or remotely), pass a `pulsar://`
+URI instead and the helper acts as a thin wrapper over `pulsar.Client`:
+
+```python
+import pulsar
+from pulsar_lite import PulsarClient
+
+with PulsarClient("pulsar://localhost:6650") as client:
+    producer = client.create_producer("non-persistent://public/default/events")
+    producer.send(b"event-1")
+```
+
+You can also skip the helper entirely and use the official client directly,
+since the broker speaks the standard Pulsar binary protocol:
+
+```python
+import pulsar
+
+client = pulsar.Client("pulsar://localhost:6650")
+```
+
+## Explicit broker lifecycle
+
+For cases where you want to start the broker and then connect with the official
+client (or multiple clients), use `start_broker`:
+
+```python
+import pulsar
+from pulsar_lite import start_broker
+
+with start_broker("./demo.db") as broker:
+    client = pulsar.Client(broker.url)
+    # ... use the official client against broker.url ...
+    client.close()
+```
+
+## API
+
+### `PulsarClient(uri, **kwargs)`
+
+- `uri`:
+  - A local file path (e.g. `"./demo.db"`) starts an embedded broker.
+  - A `pulsar://` or `pulsar+ssl://` URI connects to an existing broker.
+- `**kwargs` are forwarded to `pulsar.Client`.
+- Any attribute access not defined on `PulsarClient` itself is forwarded to the
+  underlying `pulsar.Client`, so the standard Pulsar API (`create_producer`,
+  `subscribe`, `get_topic_partitions`, ...) is fully available.
+- Supports `with` statements and auto-closes the embedded broker on exit.
+
+Properties:
+
+| Property | Description |
+| --- | --- |
+| `is_embedded` | `True` when the helper started a local broker. |
+| `db_path` | The absolute local file path (embedded mode only). |
+| `pulsar_url` | The `pulsar://localhost:<port>` URL the client connects to. |
+
+### `start_broker(db_path) -> BrokerHandle`
+
+Starts (or reuses) an embedded broker for the given path and returns a
+`BrokerHandle` with `.url`, `.port`, and a `.stop()` method. Use it as a
+context manager for automatic cleanup.
+
+## Topic names and subscription modes
+
+Pulsar Lite accepts standard Pulsar topic URIs:
+
+```text
+persistent://public/default/my-topic
+non-persistent://public/default/my-topic
+```
+
+Use `non-persistent://...` for live event dispatch where slow or disconnected
+consumers should not create a durable backlog. Use `persistent://...` when a
+test requires stored entries, cursor replay, or acknowledgements across restart
+(requires a broker binary built with RocksDB storage support).
+
+Supported subscription modes:
+
+| Mode | Summary |
+| --- | --- |
+| Exclusive | One active consumer; additional consumers are rejected. |
+| Failover | One active consumer with standby takeover. |
+| Shared | Messages are distributed across available consumers. |
+| KeyShared | Messages with the same key are routed to the same consumer. |
+
+## Binary discovery
+
+The helper looks for the bundled broker binary in this order:
+
+1. The `pulsar_lite/bin/` directory shipped inside the wheel.
+2. The `PULSAR_LITE_BINARY` environment variable.
+3. The Rust release output at `rust/target/release/pulsar-lite` (development mode).
+4. The system `PATH`.
+5. Common install locations such as `/usr/local/bin/pulsar-lite`.
+
+If you build the broker yourself, point `PULSAR_LITE_BINARY` at the resulting
+binary instead of reinstalling the package.
+
+## Building the broker from source
+
+If no prebuilt wheel matches your platform, build the broker from source and
+let the helper discover it via `PULSAR_LITE_BINARY`:
+
+```bash
+git clone https://github.com/ascentstream/pulsar-lite.git
+cd pulsar-lite/rust
+cargo build --release                 # core build
+cargo build --release --features rocksdb-storage   # with persistent storage
+```
+
+Then install the Python package and point it at your binary:
+
+```bash
+cd ../python
+pip install -e .
+export PULSAR_LITE_BINARY=$(pwd)/../rust/target/release/pulsar-lite
+```
+
+## Links
+
+- Source: <https://github.com/ascentstream/pulsar-lite>
+- Issues: <https://github.com/ascentstream/pulsar-lite/issues>
+- Full documentation: <https://github.com/ascentstream/pulsar-lite#readme>
+
+## Project boundaries
+
+Pulsar Lite intentionally does not provide:
+
+- Multi-broker coordination or load balancing.
+- Cross-cluster replication.
+- Production-grade authorization or tenant governance.
+- BookKeeper compatibility.
+- Production durability or availability guarantees.
+
+The project is useful for local development and compatibility testing, but
+production deployments should use Apache Pulsar.
+
+## License
+
+Pulsar Lite is licensed under the [Apache License 2.0](https://github.com/ascentstream/pulsar-lite/blob/main/LICENSE).

pulsar_lite-0.1.0/README.md

@@ -0,0 +1,212 @@
+# Pulsar Lite
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ascentstream/pulsar-lite/blob/main/LICENSE)
+
+Pulsar Lite is a lightweight local broker that implements the core Apache Pulsar
+binary protocol. This package ships a small Python helper that can start and
+manage a local broker process, so you can use Pulsar topic names and the
+official Pulsar Python client with a single local file path.
+
+It is designed for fast local feedback, not as a production replacement for an
+Apache Pulsar cluster. Use Apache Pulsar for production workloads that require
+multi-broker scheduling, replication, capacity management, tenant isolation, or
+operational SLAs.
+
+## Why use the Python helper
+
+Many applications only need a local broker to validate the messaging path:
+producers, consumers, subscriptions, flow control, failover, and key-based
+routing. Setting up a full Pulsar deployment can be more expensive than the
+test or prototype itself.
+
+`pulsar-lite` keeps the client-facing API close to Pulsar while removing the
+local setup cost:
+
+- Start a local broker by passing a file path, no manual process management.
+- Connect with the official `pulsar-client` (installed automatically).
+- Use Pulsar topic names such as `persistent://...` and `non-persistent://...`.
+- Exercise Shared, Failover, Exclusive, and KeyShared subscription behavior.
+
+## Installation
+
+```bash
+pip install pulsar-lite
+```
+
+The package declares `pulsar-client>=3.0.0` as a runtime dependency, so the
+official Pulsar Python client is installed automatically.
+
+Platform wheels include a prebuilt broker binary. If no wheel matches your
+platform, see the [build from source](#building-the-broker-from-source) section.
+
+## Quick start: embedded mode
+
+Pass a local file path and the helper starts a broker process for you:
+
+```python
+import pulsar
+from pulsar_lite import PulsarClient
+
+topic = "non-persistent://public/default/quick-start"
+
+with PulsarClient("./demo.db") as client:
+    consumer = client.subscribe(
+        topic,
+        "quick-start-sub",
+        consumer_type=pulsar.ConsumerType.Shared,
+    )
+    producer = client.create_producer(topic)
+
+    producer.send(b"hello from pulsar lite")
+    message = consumer.receive(timeout_millis=5000)
+    print(message.data().decode("utf-8"))
+    consumer.acknowledge(message)
+```
+
+When the `PulsarClient` context exits, the embedded broker process is stopped
+automatically (reference counted, so multiple clients on the same path share
+one broker).
+
+## Quick start: remote mode
+
+If you already have a broker running (locally or remotely), pass a `pulsar://`
+URI instead and the helper acts as a thin wrapper over `pulsar.Client`:
+
+```python
+import pulsar
+from pulsar_lite import PulsarClient
+
+with PulsarClient("pulsar://localhost:6650") as client:
+    producer = client.create_producer("non-persistent://public/default/events")
+    producer.send(b"event-1")
+```
+
+You can also skip the helper entirely and use the official client directly,
+since the broker speaks the standard Pulsar binary protocol:
+
+```python
+import pulsar
+
+client = pulsar.Client("pulsar://localhost:6650")
+```
+
+## Explicit broker lifecycle
+
+For cases where you want to start the broker and then connect with the official
+client (or multiple clients), use `start_broker`:
+
+```python
+import pulsar
+from pulsar_lite import start_broker
+
+with start_broker("./demo.db") as broker:
+    client = pulsar.Client(broker.url)
+    # ... use the official client against broker.url ...
+    client.close()
+```
+
+## API
+
+### `PulsarClient(uri, **kwargs)`
+
+- `uri`:
+  - A local file path (e.g. `"./demo.db"`) starts an embedded broker.
+  - A `pulsar://` or `pulsar+ssl://` URI connects to an existing broker.
+- `**kwargs` are forwarded to `pulsar.Client`.
+- Any attribute access not defined on `PulsarClient` itself is forwarded to the
+  underlying `pulsar.Client`, so the standard Pulsar API (`create_producer`,
+  `subscribe`, `get_topic_partitions`, ...) is fully available.
+- Supports `with` statements and auto-closes the embedded broker on exit.
+
+Properties:
+
+| Property | Description |
+| --- | --- |
+| `is_embedded` | `True` when the helper started a local broker. |
+| `db_path` | The absolute local file path (embedded mode only). |
+| `pulsar_url` | The `pulsar://localhost:<port>` URL the client connects to. |
+
+### `start_broker(db_path) -> BrokerHandle`
+
+Starts (or reuses) an embedded broker for the given path and returns a
+`BrokerHandle` with `.url`, `.port`, and a `.stop()` method. Use it as a
+context manager for automatic cleanup.
+
+## Topic names and subscription modes
+
+Pulsar Lite accepts standard Pulsar topic URIs:
+
+```text
+persistent://public/default/my-topic
+non-persistent://public/default/my-topic
+```
+
+Use `non-persistent://...` for live event dispatch where slow or disconnected
+consumers should not create a durable backlog. Use `persistent://...` when a
+test requires stored entries, cursor replay, or acknowledgements across restart
+(requires a broker binary built with RocksDB storage support).
+
+Supported subscription modes:
+
+| Mode | Summary |
+| --- | --- |
+| Exclusive | One active consumer; additional consumers are rejected. |
+| Failover | One active consumer with standby takeover. |
+| Shared | Messages are distributed across available consumers. |
+| KeyShared | Messages with the same key are routed to the same consumer. |
+
+## Binary discovery
+
+The helper looks for the bundled broker binary in this order:
+
+1. The `pulsar_lite/bin/` directory shipped inside the wheel.
+2. The `PULSAR_LITE_BINARY` environment variable.
+3. The Rust release output at `rust/target/release/pulsar-lite` (development mode).
+4. The system `PATH`.
+5. Common install locations such as `/usr/local/bin/pulsar-lite`.
+
+If you build the broker yourself, point `PULSAR_LITE_BINARY` at the resulting
+binary instead of reinstalling the package.
+
+## Building the broker from source
+
+If no prebuilt wheel matches your platform, build the broker from source and
+let the helper discover it via `PULSAR_LITE_BINARY`:
+
+```bash
+git clone https://github.com/ascentstream/pulsar-lite.git
+cd pulsar-lite/rust
+cargo build --release                 # core build
+cargo build --release --features rocksdb-storage   # with persistent storage
+```
+
+Then install the Python package and point it at your binary:
+
+```bash
+cd ../python
+pip install -e .
+export PULSAR_LITE_BINARY=$(pwd)/../rust/target/release/pulsar-lite
+```
+
+## Links
+
+- Source: <https://github.com/ascentstream/pulsar-lite>
+- Issues: <https://github.com/ascentstream/pulsar-lite/issues>
+- Full documentation: <https://github.com/ascentstream/pulsar-lite#readme>
+
+## Project boundaries
+
+Pulsar Lite intentionally does not provide:
+
+- Multi-broker coordination or load balancing.
+- Cross-cluster replication.
+- Production-grade authorization or tenant governance.
+- BookKeeper compatibility.
+- Production durability or availability guarantees.
+
+The project is useful for local development and compatibility testing, but
+production deployments should use Apache Pulsar.
+
+## License
+
+Pulsar Lite is licensed under the [Apache License 2.0](https://github.com/ascentstream/pulsar-lite/blob/main/LICENSE).

pulsar_lite-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pulsar-lite"
+version = "0.1.0"
+description = "Embedded Apache Pulsar-compatible broker for local development"
+authors = [{name = "Ascentstream", email = "community@ascentstream.com"}]
+license = {text = "Apache-2.0"}
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pulsar-client>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "black>=23.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ascentstream/pulsar-lite"
+Documentation = "https://github.com/ascentstream/pulsar-lite#readme"
+Repository = "https://github.com/ascentstream/pulsar-lite"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pulsar_lite = ["bin/pulsar-lite", "bin/pulsar-lite.exe"]
+
+[tool.black]
+line-length = 100
+target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+select = ["E", "F", "I", "N", "W"]

pulsar_lite-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pulsar_lite-0.1.0/setup.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Pulsar Lite setup customizations."""
+
+import platform
+import sys
+import sysconfig
+
+from setuptools import setup
+
+try:
+    from setuptools.command.bdist_wheel import bdist_wheel
+except ImportError:
+    from wheel.bdist_wheel import bdist_wheel
+
+
+class bdist_platform_wheel(bdist_wheel):
+    """Build py3-none-platform wheels for the bundled Rust broker binary."""
+
+    def finalize_options(self):
+        super().finalize_options()
+        self.root_is_pure = False
+
+    def get_tag(self):
+        if self.plat_name_supplied:
+            plat_name = self.plat_name
+        elif self.plat_name and not self.plat_name.startswith("macosx"):
+            plat_name = self.plat_name
+        else:
+            plat_name = sysconfig.get_platform()
+            plat_name = _native_macos_platform(plat_name)
+
+        # Normalize to PEP 425 form (lowercase, underscores, no dots).
+        plat_name = plat_name.lower().replace("-", "_").replace(".", "_")
+
+        # PyPI rejects bare "linux_*" platform tags (PEP 513/599/600). The
+        # bundled Rust broker is a static binary with no glibc/ELIB coupling,
+        # so we relabel Linux wheels to manylinux_2_17 which is accepted by
+        # PyPI and works on any glibc >= 2.17 (CentOS 7+) distribution.
+        if plat_name == "linux_x86_64":
+            plat_name = "manylinux_2_17_x86_64"
+        elif plat_name == "linux_i686":
+            plat_name = "manylinux_2_17_i686"
+        elif plat_name == "linux_aarch64":
+            plat_name = "manylinux_2_17_aarch64"
+
+        # 32-bit x86 fallback for legacy i686 detection.
+        if plat_name in ("linux-x86_64", "linux_x86_64") and sys.maxsize == 2147483647:
+            plat_name = "manylinux_2_17_i686"
+
+        return self.python_tag, "none", plat_name
+
+
+def _native_macos_platform(plat_name):
+    if not plat_name.startswith("macosx") or "universal2" not in plat_name:
+        return plat_name
+
+    machine = platform.machine().lower()
+    if machine in ("arm64", "aarch64"):
+        return "macosx-11.0-arm64"
+    if machine in ("x86_64", "amd64"):
+        return "macosx-10.9-x86_64"
+    return plat_name
+
+
+if __name__ == "__main__":
+    setup(cmdclass={"bdist_wheel": bdist_platform_wheel})

pulsar_lite-0.1.0/src/pulsar_lite/__init__.py

@@ -0,0 +1,31 @@
+"""
+Pulsar Lite - 嵌入式轻量级消息队列
+
+使用方式类似 Milvus Lite：
+    from pulsar_lite import PulsarClient
+
+    # 嵌入式模式 - 使用本地文件自动启动
+    client = PulsarClient("./milvus_demo.db")
+
+    # 远程模式 - 连接到远程服务器
+    client = PulsarClient("pulsar://localhost:6650")
+
+    # 使用标准 Pulsar API
+    producer = client.create_producer("my-topic")
+    producer.send(b"Hello World!")
+    client.close()
+
+    # 显式启动 broker，然后使用官方 pulsar-client
+    from pulsar_lite import start_broker
+    import pulsar
+
+    broker = start_broker("./milvus_demo.db")
+    client = pulsar.Client(broker.url)
+"""
+
+__version__ = "0.1.0"
+
+from .client import PulsarClient
+from .process_manager import BrokerHandle, start_broker
+
+__all__ = ["BrokerHandle", "PulsarClient", "start_broker", "__version__"]

pulsar_lite-0.1.0/src/pulsar_lite/binary_finder.py

@@ -0,0 +1,69 @@
+"""
+查找 Pulsar Lite 二进制文件
+"""
+
+import os
+import sys
+import shutil
+from pathlib import Path
+from typing import Optional
+
+
+def find_pulsar_lite_binary() -> str:
+    """
+    查找 pulsar-lite 可执行文件
+
+    搜索顺序：
+    1. Python 包内置二进制（pip wheel 安装模式）
+    2. 环境变量 PULSAR_LITE_BINARY
+    3. 当前 Python 包目录的相对路径（开发模式）
+    4. 系统 PATH
+    5. 常见安装位置
+
+    Returns:
+        二进制文件的绝对路径
+
+    Raises:
+        FileNotFoundError: 找不到二进制文件
+    """
+    # 1. 检查 Python 包内置二进制
+    package_binary_name = "pulsar-lite.exe" if sys.platform.startswith("win") else "pulsar-lite"
+    packaged_binary = Path(__file__).parent / "bin" / package_binary_name
+    if packaged_binary.is_file():
+        return str(packaged_binary.absolute())
+
+    # 2. 检查环境变量
+    env_path = os.environ.get("PULSAR_LITE_BINARY")
+    if env_path and os.path.isfile(env_path):
+        return os.path.abspath(env_path)
+
+    # 3. 开发模式：相对于当前包的路径
+    package_dir = Path(__file__).parent.parent.parent.parent  # python/src/pulsar_lite -> 项目根目录
+    dev_binary = package_dir / "rust" / "target" / "release" / "pulsar-lite"
+    if dev_binary.exists():
+        return str(dev_binary.absolute())
+
+    # 4. 在 PATH 中查找
+    binary_name = package_binary_name
+    in_path = shutil.which(binary_name)
+    if in_path:
+        return in_path
+
+    # 5. 常见安装位置
+    common_paths = [
+        "/usr/local/bin/pulsar-lite",
+        "/usr/bin/pulsar-lite",
+        Path.home() / ".local" / "bin" / "pulsar-lite",
+    ]
+
+    for path in common_paths:
+        path = Path(path)
+        if path.exists():
+            return str(path.absolute())
+
+    raise FileNotFoundError(
+        "Pulsar Lite binary not found. Please either:\n"
+        "1. Set PULSAR_LITE_BINARY environment variable\n"
+        "2. Build from source: cd rust && cargo build --release\n"
+        "3. Install pulsar-lite to your PATH"
+    )

pulsar_lite-0.1.0/src/pulsar_lite/client.py

@@ -0,0 +1,116 @@
+"""
+Pulsar Lite 客户端
+
+提供与 Milvus Lite 类似的无缝体验：
+- 本地文件路径 → 自动启动嵌入式服务器
+- 远程 URI → 直接连接远程服务器
+"""
+
+import pulsar
+from pathlib import Path
+from typing import Optional, Any
+from .process_manager import process_manager
+
+
+class PulsarClient:
+    """
+    Pulsar Lite 客户端（兼容 Pulsar Python SDK API）
+
+    使用方式类似 Milvus Lite：
+        # 嵌入式模式 - 使用本地文件自动启动
+        client = PulsarClient("./demo.db")
+
+        # 远程模式 - 连接到远程服务器
+        client = PulsarClient("pulsar://localhost:6650")
+
+        # 后续使用完全兼容 pulsar.Client API
+        producer = client.create_producer("my-topic")
+        producer.send(b"Hello")
+    """
+
+    def __init__(self, uri: str, **kwargs):
+        """
+        初始化客户端
+
+        Args:
+            uri: 连接地址，可以是：
+                - 本地文件路径（如 "./demo.db"）→ 自动启动嵌入式服务器
+                - Pulsar URI（如 "pulsar://localhost:6650"）→ 直接连接远程
+            **kwargs: 传递给 pulsar.Client 的其他参数
+        """
+        self._original_uri = uri
+        self._db_path: Optional[str] = None
+        self._is_embedded = False
+        self._client: Optional[pulsar.Client] = None
+
+        # 判断是本地文件还是远程 URI
+        is_remote = uri.startswith("pulsar://") or uri.startswith("pulsar+ssl://")
+
+        if is_remote:
+            # 远程模式：直接连接
+            self._pulsar_url = uri
+        else:
+            # 嵌入式模式：启动本地服务器
+            self._db_path = str(Path(uri).absolute())
+            self._pulsar_url, self._port = process_manager.start_server(self._db_path)
+            self._is_embedded = True
+
+        # 创建实际的 Pulsar 客户端
+        self._client = pulsar.Client(self._pulsar_url, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        代理所有其他方法到 pulsar.Client
+
+        这样用户可以使用所有标准的 Pulsar API，如：
+        - create_producer
+        - subscribe
+        - get_topic_partitions
+        - 等等...
+        """
+        if self._client is None:
+            raise RuntimeError("Client has been closed")
+
+        return getattr(self._client, name)
+
+    def close(self):
+        """关闭客户端并释放资源"""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+        # 如果是嵌入式模式，停止服务器
+        if self._is_embedded and self._db_path:
+            process_manager.stop_server(self._db_path)
+            self._is_embedded = False
+
+    def __enter__(self):
+        """支持 with 语句"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """退出 with 语句时自动关闭"""
+        self.close()
+        return False
+
+    def __del__(self):
+        """析构时自动关闭"""
+        try:
+            self.close()
+        except:
+            pass
+
+    @property
+    def is_embedded(self) -> bool:
+        """是否为嵌入式模式"""
+        return self._is_embedded
+
+    @property
+    def db_path(self) -> Optional[str]:
+        """数据库文件路径（仅嵌入式模式有效）"""
+        return self._db_path
+
+    @property
+    def pulsar_url(self) -> str:
+        """Pulsar 连接 URL"""
+        return self._pulsar_url

pulsar_lite-0.1.0/src/pulsar_lite/process_manager.py

@@ -0,0 +1,236 @@
+"""
+Pulsar Lite 进程管理器
+
+参考 Milvus Lite 的实现，管理嵌入式服务器进程
+支持多个客户端共享同一服务器实例
+"""
+
+import os
+import subprocess
+import time
+import threading
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Tuple, Optional
+from .binary_finder import find_pulsar_lite_binary
+
+
+@dataclass
+class BrokerHandle:
+    """Handle for an embedded Pulsar Lite broker process."""
+
+    db_path: str
+    url: str
+    port: int
+
+    def stop(self):
+        """Release this handle and stop the broker when no clients remain."""
+        process_manager.stop_server(self.db_path)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+        return False
+
+
+class ProcessManager:
+    """
+    单例进程管理器
+
+    职责：
+    1. 启动/停止 Pulsar Lite 服务器进程
+    2. 引用计数：支持多个客户端共享同一实例
+    3. 自动端口分配
+    4. 线程安全
+    """
+
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if self._initialized:
+            return
+
+        self._initialized = True
+        self._processes: Dict[str, Tuple[subprocess.Popen, int, int]] = {}  # db_path -> (process, ref_count, port)
+        self._process_lock = threading.Lock()
+        self._binary_path = None
+
+    def _find_free_port(self, start_port: int = 6650) -> int:
+        """查找可用端口"""
+        port = start_port
+        while port < 6700:
+            try:
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                    s.bind(("127.0.0.1", port))
+                    return port
+            except OSError:
+                port += 1
+        raise RuntimeError("No available port found")
+
+    def _wait_until_ready(self, process: subprocess.Popen, port: int, timeout: float = 10.0):
+        """Wait until the broker accepts TCP connections on the selected port."""
+        deadline = time.time() + timeout
+        last_error = None
+
+        while time.time() < deadline:
+            if process.poll() is not None:
+                raise RuntimeError("Pulsar Lite server exited before accepting connections")
+
+            try:
+                with socket.create_connection(("127.0.0.1", port), timeout=0.25):
+                    return
+            except OSError as error:
+                last_error = error
+                time.sleep(0.1)
+
+        try:
+            process.terminate()
+            process.wait(timeout=5)
+        except Exception:
+            process.kill()
+            process.wait()
+        raise RuntimeError(f"Pulsar Lite server did not become ready on port {port}: {last_error}")
+
+    def _is_remote_uri(self, uri: str) -> bool:
+        """判断是否为远程 URI"""
+        return uri.startswith("pulsar://") or uri.startswith("pulsar+ssl://")
+
+    def start_server(self, db_path: str) -> Tuple[str, int]:
+        """
+        启动嵌入式服务器
+
+        Args:
+            db_path: 数据库文件路径
+
+        Returns:
+            (pulsar_url, port) - Pulsar 连接 URL 和端口号
+
+        Raises:
+            RuntimeError: 启动失败
+        """
+        # 规范化路径
+        db_path = str(Path(db_path).absolute())
+
+        with self._process_lock:
+            # 如果已经运行，增加引用计数
+            if db_path in self._processes:
+                process, ref_count, port = self._processes[db_path]
+                self._processes[db_path] = (process, ref_count + 1, port)
+                print(f"Reusing Pulsar Lite server for {db_path}, ref_count={ref_count + 1}, port={port}")
+                return f"pulsar://localhost:{port}", port
+
+            # 查找二进制文件
+            if self._binary_path is None:
+                self._binary_path = find_pulsar_lite_binary()
+
+            # 查找可用端口
+            port = self._find_free_port()
+            addr = f"127.0.0.1:{port}"
+
+            # 确保数据库目录存在
+            db_dir = Path(db_path).parent
+            db_dir.mkdir(parents=True, exist_ok=True)
+
+            # 启动进程，日志输出到 /tmp/pulsar-lite.log
+            env = {**os.environ, "RUST_LOG": "info"}
+            log_file = open("/tmp/pulsar-lite.log", "a")
+            process = subprocess.Popen(
+                [
+                    self._binary_path,
+                    "--addr",
+                    addr,
+                    "--db-path",
+                    db_path,
+                ],
+                env=env,
+                stdout=log_file,
+                stderr=log_file,
+                cwd=str(db_dir)
+            )
+
+            try:
+                self._wait_until_ready(process, port)
+            except RuntimeError as error:
+                raise RuntimeError(f"Pulsar Lite server failed to start for {db_path}: {error}") from error
+
+            # 保存进程信息
+            self._processes[db_path] = (process, 1, port)
+            print(f"Started Pulsar Lite server for {db_path}, ref_count=1, port={port}, pid={process.pid}")
+
+            return f"pulsar://localhost:{port}", port
+
+    def start_broker(self, db_path: str) -> BrokerHandle:
+        """Start or reuse an embedded broker and return an explicit lifecycle handle."""
+        url, port = self.start_server(db_path)
+        return BrokerHandle(db_path=str(Path(db_path).absolute()), url=url, port=port)
+
+    def stop_server(self, db_path: str):
+        """
+        停止嵌入式服务器（减少引用计数，为0时真正停止）
+
+        Args:
+            db_path: 数据库文件路径
+        """
+        db_path = str(Path(db_path).absolute())
+
+        with self._process_lock:
+            if db_path not in self._processes:
+                return
+
+            process, ref_count, port = self._processes[db_path]
+            ref_count -= 1
+
+            if ref_count == 0:
+                # 引用计数为0，停止服务器
+                print(f"Stopping Pulsar Lite server for {db_path}, pid={process.pid}")
+                try:
+                    process.terminate()
+                    process.wait(timeout=5)
+                except:
+                    process.kill()
+                    process.wait()
+
+                del self._processes[db_path]
+                print(f"Stopped Pulsar Lite server for {db_path}")
+            else:
+                # 更新引用计数
+                self._processes[db_path] = (process, ref_count, port)
+                print(f"Decreased ref_count for {db_path}, ref_count={ref_count}")
+
+    def stop_all(self):
+        """停止所有服务器"""
+        with self._process_lock:
+            for db_path, (process, _, _) in list(self._processes.items()):
+                print(f"Stopping Pulsar Lite server for {db_path}, pid={process.pid}")
+                try:
+                    process.terminate()
+                    process.wait(timeout=5)
+                except:
+                    process.kill()
+                    process.wait()
+
+            self._processes.clear()
+
+    def __del__(self):
+        self.stop_all()
+
+
+# 全局单例
+process_manager = ProcessManager()
+
+
+def start_broker(db_path: str) -> BrokerHandle:
+    """Start or reuse an embedded Pulsar Lite broker."""
+    return process_manager.start_broker(db_path)

pulsar_lite-0.1.0/src/pulsar_lite.egg-info/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: pulsar-lite
+Version: 0.1.0
+Summary: Embedded Apache Pulsar-compatible broker for local development
+Author-email: Ascentstream <community@ascentstream.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ascentstream/pulsar-lite
+Project-URL: Documentation, https://github.com/ascentstream/pulsar-lite#readme
+Project-URL: Repository, https://github.com/ascentstream/pulsar-lite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pulsar-client>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# Pulsar Lite
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ascentstream/pulsar-lite/blob/main/LICENSE)
+
+Pulsar Lite is a lightweight local broker that implements the core Apache Pulsar
+binary protocol. This package ships a small Python helper that can start and
+manage a local broker process, so you can use Pulsar topic names and the
+official Pulsar Python client with a single local file path.
+
+It is designed for fast local feedback, not as a production replacement for an
+Apache Pulsar cluster. Use Apache Pulsar for production workloads that require
+multi-broker scheduling, replication, capacity management, tenant isolation, or
+operational SLAs.
+
+## Why use the Python helper
+
+Many applications only need a local broker to validate the messaging path:
+producers, consumers, subscriptions, flow control, failover, and key-based
+routing. Setting up a full Pulsar deployment can be more expensive than the
+test or prototype itself.
+
+`pulsar-lite` keeps the client-facing API close to Pulsar while removing the
+local setup cost:
+
+- Start a local broker by passing a file path, no manual process management.
+- Connect with the official `pulsar-client` (installed automatically).
+- Use Pulsar topic names such as `persistent://...` and `non-persistent://...`.
+- Exercise Shared, Failover, Exclusive, and KeyShared subscription behavior.
+
+## Installation
+
+```bash
+pip install pulsar-lite
+```
+
+The package declares `pulsar-client>=3.0.0` as a runtime dependency, so the
+official Pulsar Python client is installed automatically.
+
+Platform wheels include a prebuilt broker binary. If no wheel matches your
+platform, see the [build from source](#building-the-broker-from-source) section.
+
+## Quick start: embedded mode
+
+Pass a local file path and the helper starts a broker process for you:
+
+```python
+import pulsar
+from pulsar_lite import PulsarClient
+
+topic = "non-persistent://public/default/quick-start"
+
+with PulsarClient("./demo.db") as client:
+    consumer = client.subscribe(
+        topic,
+        "quick-start-sub",
+        consumer_type=pulsar.ConsumerType.Shared,
+    )
+    producer = client.create_producer(topic)
+
+    producer.send(b"hello from pulsar lite")
+    message = consumer.receive(timeout_millis=5000)
+    print(message.data().decode("utf-8"))
+    consumer.acknowledge(message)
+```
+
+When the `PulsarClient` context exits, the embedded broker process is stopped
+automatically (reference counted, so multiple clients on the same path share
+one broker).
+
+## Quick start: remote mode
+
+If you already have a broker running (locally or remotely), pass a `pulsar://`
+URI instead and the helper acts as a thin wrapper over `pulsar.Client`:
+
+```python
+import pulsar
+from pulsar_lite import PulsarClient
+
+with PulsarClient("pulsar://localhost:6650") as client:
+    producer = client.create_producer("non-persistent://public/default/events")
+    producer.send(b"event-1")
+```
+
+You can also skip the helper entirely and use the official client directly,
+since the broker speaks the standard Pulsar binary protocol:
+
+```python
+import pulsar
+
+client = pulsar.Client("pulsar://localhost:6650")
+```
+
+## Explicit broker lifecycle
+
+For cases where you want to start the broker and then connect with the official
+client (or multiple clients), use `start_broker`:
+
+```python
+import pulsar
+from pulsar_lite import start_broker
+
+with start_broker("./demo.db") as broker:
+    client = pulsar.Client(broker.url)
+    # ... use the official client against broker.url ...
+    client.close()
+```
+
+## API
+
+### `PulsarClient(uri, **kwargs)`
+
+- `uri`:
+  - A local file path (e.g. `"./demo.db"`) starts an embedded broker.
+  - A `pulsar://` or `pulsar+ssl://` URI connects to an existing broker.
+- `**kwargs` are forwarded to `pulsar.Client`.
+- Any attribute access not defined on `PulsarClient` itself is forwarded to the
+  underlying `pulsar.Client`, so the standard Pulsar API (`create_producer`,
+  `subscribe`, `get_topic_partitions`, ...) is fully available.
+- Supports `with` statements and auto-closes the embedded broker on exit.
+
+Properties:
+
+| Property | Description |
+| --- | --- |
+| `is_embedded` | `True` when the helper started a local broker. |
+| `db_path` | The absolute local file path (embedded mode only). |
+| `pulsar_url` | The `pulsar://localhost:<port>` URL the client connects to. |
+
+### `start_broker(db_path) -> BrokerHandle`
+
+Starts (or reuses) an embedded broker for the given path and returns a
+`BrokerHandle` with `.url`, `.port`, and a `.stop()` method. Use it as a
+context manager for automatic cleanup.
+
+## Topic names and subscription modes
+
+Pulsar Lite accepts standard Pulsar topic URIs:
+
+```text
+persistent://public/default/my-topic
+non-persistent://public/default/my-topic
+```
+
+Use `non-persistent://...` for live event dispatch where slow or disconnected
+consumers should not create a durable backlog. Use `persistent://...` when a
+test requires stored entries, cursor replay, or acknowledgements across restart
+(requires a broker binary built with RocksDB storage support).
+
+Supported subscription modes:
+
+| Mode | Summary |
+| --- | --- |
+| Exclusive | One active consumer; additional consumers are rejected. |
+| Failover | One active consumer with standby takeover. |
+| Shared | Messages are distributed across available consumers. |
+| KeyShared | Messages with the same key are routed to the same consumer. |
+
+## Binary discovery
+
+The helper looks for the bundled broker binary in this order:
+
+1. The `pulsar_lite/bin/` directory shipped inside the wheel.
+2. The `PULSAR_LITE_BINARY` environment variable.
+3. The Rust release output at `rust/target/release/pulsar-lite` (development mode).
+4. The system `PATH`.
+5. Common install locations such as `/usr/local/bin/pulsar-lite`.
+
+If you build the broker yourself, point `PULSAR_LITE_BINARY` at the resulting
+binary instead of reinstalling the package.
+
+## Building the broker from source
+
+If no prebuilt wheel matches your platform, build the broker from source and
+let the helper discover it via `PULSAR_LITE_BINARY`:
+
+```bash
+git clone https://github.com/ascentstream/pulsar-lite.git
+cd pulsar-lite/rust
+cargo build --release                 # core build
+cargo build --release --features rocksdb-storage   # with persistent storage
+```
+
+Then install the Python package and point it at your binary:
+
+```bash
+cd ../python
+pip install -e .
+export PULSAR_LITE_BINARY=$(pwd)/../rust/target/release/pulsar-lite
+```
+
+## Links
+
+- Source: <https://github.com/ascentstream/pulsar-lite>
+- Issues: <https://github.com/ascentstream/pulsar-lite/issues>
+- Full documentation: <https://github.com/ascentstream/pulsar-lite#readme>
+
+## Project boundaries
+
+Pulsar Lite intentionally does not provide:
+
+- Multi-broker coordination or load balancing.
+- Cross-cluster replication.
+- Production-grade authorization or tenant governance.
+- BookKeeper compatibility.
+- Production durability or availability guarantees.
+
+The project is useful for local development and compatibility testing, but
+production deployments should use Apache Pulsar.
+
+## License
+
+Pulsar Lite is licensed under the [Apache License 2.0](https://github.com/ascentstream/pulsar-lite/blob/main/LICENSE).

pulsar_lite-0.1.0/src/pulsar_lite.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+setup.py
+src/pulsar_lite/__init__.py
+src/pulsar_lite/binary_finder.py
+src/pulsar_lite/client.py
+src/pulsar_lite/process_manager.py
+src/pulsar_lite.egg-info/PKG-INFO
+src/pulsar_lite.egg-info/SOURCES.txt
+src/pulsar_lite.egg-info/dependency_links.txt
+src/pulsar_lite.egg-info/requires.txt
+src/pulsar_lite.egg-info/top_level.txt
+src/pulsar_lite/bin/pulsar-lite

pulsar_lite-0.1.0/src/pulsar_lite.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pulsar_lite-0.1.0/src/pulsar_lite.egg-info/requires.txt

@@ -0,0 +1,6 @@
+pulsar-client>=3.0.0
+
+[dev]
+pytest>=7.0
+black>=23.0
+ruff>=0.1.0

pulsar_lite-0.1.0/src/pulsar_lite.egg-info/top_level.txt

@@ -0,0 +1 @@
+pulsar_lite