pulse-broker 1.0.8__py3-none-any.whl

pulse/__init__.py

@@ -0,0 +1,15 @@
+# Try to update proto first
+try:
+    from .proto_manager import ensure_proto
+    import os
+    host = os.environ.get("PULSE_HOST", "localhost")
+    port = int(os.environ.get("PULSE_HTTP_PORT", "5555"))
+    ensure_proto(host, port)
+except Exception:
+    pass
+
+from .producer import Producer
+from .consumer import consumer, commit, run
+from .config import load_config
+
+__all__ = ["Producer", "consumer", "commit", "run", "load_config"]

pulse/config.py

@@ -0,0 +1,59 @@
+import os
+import yaml
+
+DEFAULT_CONFIG = {
+    "broker": {
+        "host": "localhost",
+        "http_port": 5555,
+        "grpc_port": 5556,
+        "timeout_ms": 5000
+    },
+    "client": {
+        "id": "python-client",
+        "auto_commit": True,
+        "max_retries": 3
+    },
+    "topics": []
+}
+
+def load_config(path=None):
+    """
+    Load configuration from a YAML file.
+    If path is not provided, looks for pulse.yaml or pulse.yml in the current directory.
+    """
+    if not path:
+        if os.path.exists("pulse.yaml"):
+            path = "pulse.yaml"
+        elif os.path.exists("pulse.yml"):
+            path = "pulse.yml"
+    
+    config = DEFAULT_CONFIG.copy()
+    
+    if path and os.path.exists(path):
+        with open(path, "r") as f:
+            file_config = yaml.safe_load(f)
+            if file_config:
+                _merge_dicts(config, file_config)
+    
+    return config
+
+def _merge_dicts(base, update):
+    """Recursively merge dictionaries."""
+    for k, v in update.items():
+        if isinstance(v, dict) and k in base and isinstance(base[k], dict):
+            _merge_dicts(base[k], v)
+        else:
+            base[k] = v
+
+# Global config instance
+_config = load_config()
+
+def get_config():
+    return _config
+
+def get_topic_config(topic_name):
+    """Get configuration for a specific topic."""
+    for topic in _config.get("topics", []):
+        if topic.get("name") == topic_name:
+            return topic
+    return None

pulse/consumer.py

@@ -0,0 +1,260 @@
+import grpc
+import threading
+import time
+import contextvars
+import json
+from .config import get_config, get_topic_config
+from .proto import pulse_pb2, pulse_pb2_grpc
+
+# Registry of registered consumers
+_consumers = []
+
+# Context variable to hold the current message context for manual commit
+_current_context = contextvars.ContextVar("current_context", default=None)
+
+class MessageContext:
+    def __init__(self, stub, topic, consumer_group, offset):
+        self.stub = stub
+        self.topic = topic
+        self.consumer_group = consumer_group
+        self.offset = offset
+        self.committed = False
+
+def commit():
+    """
+    Manually commit the current message offset.
+    Must be called within a consumer handler.
+    """
+    ctx = _current_context.get()
+    if not ctx:
+        raise RuntimeError("commit() called outside of a consumer handler")
+    
+    if ctx.committed:
+        return
+
+    try:
+        ctx.stub.CommitOffset(pulse_pb2.CommitOffsetRequest(
+            topic=ctx.topic,
+            consumer_name=ctx.consumer_group,
+            offset=ctx.offset + 1
+        ))
+        ctx.committed = True
+    except grpc.RpcError as e:
+        print(f"Error committing offset: {e}")
+        raise e
+
+class Message:
+    def __init__(self, proto_msg):
+        self.offset = proto_msg.offset
+        self.timestamp = proto_msg.timestamp
+        self._raw_payload = proto_msg.payload
+        # Headers from the broker (map<string,string>)
+        # Some older messages may not have headers.
+        try:
+            self._headers = dict(proto_msg.headers)
+        except Exception:
+            self._headers = {}
+    
+    @property
+    def payload(self):
+        """Return payload converted to original type using headers.
+
+        header `payload-type` values: 'json', 'string', 'bytes'.
+        If missing, attempt to parse JSON and fall back to bytes.
+        """
+        ptype = self._headers.get("payload-type")
+        if ptype == "json":
+            try:
+                return json.loads(self._raw_payload)
+            except Exception:
+                return self._raw_payload
+        if ptype == "string":
+            try:
+                return self._raw_payload.decode("utf-8")
+            except Exception:
+                return self._raw_payload
+        if ptype == "bytes":
+            return self._raw_payload
+
+        # Fallback for older messages: try JSON then bytes
+        try:
+            return json.loads(self._raw_payload)
+        except Exception:
+            return self._raw_payload
+    
+    @property
+    def raw_payload(self):
+        return self._raw_payload
+
+    @property
+    def headers(self):
+        return self._headers
+
+    def __str__(self):
+        return f"Message(offset={self.offset}, payload={self.payload})"
+
+def consumer(topic, host=None, port=None, consumer_group=None, auto_commit=None, grouped=True):
+    """
+    Decorator to register a function as a consumer for a topic.
+
+    Parameters:
+    - topic: topic name
+    - consumer_group: explicit group id (overrides config client.id)
+    - grouped (bool): when True (default), handlers with the same topic+group
+      will share a single stream/consumer and messages will be distributed
+      among them. When False, the decorator will create a unique consumer
+      group id so the handler receives all messages independently.
+    """
+    def decorator(func):
+        config = get_config()
+        topic_config = get_topic_config(topic)
+
+        # Determine configuration
+        c_host = host or config["broker"]["host"]
+        c_port = port or config["broker"]["grpc_port"]
+
+        # Determine base consumer group
+        base_group = consumer_group or config["client"]["id"]
+
+        # If grouped is False, create a unique consumer id so it will consume
+        # independently of other consumers using the same app id.
+        if not grouped:
+            import uuid
+            c_group = f"{base_group}-{uuid.uuid4().hex}"
+        else:
+            c_group = base_group
+
+        # Determine auto_commit
+        c_auto_commit = auto_commit
+        if c_auto_commit is None:
+            c_auto_commit = config["client"]["auto_commit"]
+            if topic_config and "consume" in topic_config:
+                if "auto_commit" in topic_config["consume"]:
+                    c_auto_commit = topic_config["consume"]["auto_commit"]
+
+        # Register handler grouped by (topic, group). We'll keep a single
+        # _consumers entry per (topic, group) and collect handlers so a single
+        # stream can dispatch to them (avoiding duplicate delivery within the
+        # same process when using grouped=True).
+        _consumers.append({
+            "topic": topic,
+            "host": c_host,
+            "port": c_port,
+            "group": c_group,
+            "auto_commit": c_auto_commit,
+            "handler": func,
+            "grouped": grouped
+        })
+        return func
+    return decorator
+
+def run():
+    """
+    Start all registered consumers.
+    This function blocks.
+    """
+    # Coalesce consumers by (topic, group) when grouped=True so we create
+    # a single streaming connection per group and dispatch messages to the
+    # registered handlers in this process. If grouped=False was used, each
+    # entry will already have a unique group id and will be treated separately.
+    grouped_map = {}
+    for c in _consumers:
+        key = (c["topic"], c["host"], c["port"], c["group"])
+        if key not in grouped_map:
+            grouped_map[key] = {
+                "topic": c["topic"],
+                "host": c["host"],
+                "port": c["port"],
+                "group": c["group"],
+                "auto_commit": c["auto_commit"],
+                "handlers": []
+            }
+        grouped_map[key]["handlers"].append(c["handler"])
+
+    threads = []
+    for key, gc in grouped_map.items():
+        t = threading.Thread(target=_consume_loop_group, args=(gc,), daemon=True)
+        t.start()
+        threads.append(t)
+    
+    # Keep main thread alive
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("Stopping consumers...")
+
+def _consume_loop(c_config):
+    address = f"{c_config['host']}:{c_config['port']}"
+    channel = grpc.insecure_channel(address)
+    stub = pulse_pb2_grpc.PulseServiceStub(channel)
+    
+    # Backwards-compatible single-consumer loop (kept for compatibility with
+    # any direct calls). Wrap into group-style data and forward to group loop.
+    gc = {
+        "topic": c_config["topic"],
+        "host": c_config["host"],
+        "port": c_config["port"],
+        "group": c_config["group"],
+        "auto_commit": c_config["auto_commit"],
+        "handlers": [c_config.get("handler")]
+    }
+    _consume_loop_group(gc)
+
+
+def _consume_loop_group(group_config):
+    topic = group_config["topic"]
+    group = group_config["group"]
+    auto_commit = group_config["auto_commit"]
+    handlers = group_config.get("handlers", [])
+
+    address = f"{group_config['host']}:{group_config['port']}"
+    channel = grpc.insecure_channel(address)
+    stub = pulse_pb2_grpc.PulseServiceStub(channel)
+
+    print(f"Starting consumer for topic '{topic}' (group: {group}) on {address}")
+
+    # simple round-robin index for dispatching to handlers
+    handler_idx = 0
+
+    while True:
+        try:
+            request = pulse_pb2.ConsumeRequest(
+                topic=topic,
+                consumer_name=group,
+                offset=0
+            )
+            stream = stub.Consume(request)
+
+            for proto_msg in stream:
+                msg = Message(proto_msg)
+
+                # Round-robin select handler
+                if not handlers:
+                    # No handlers registered; skip
+                    continue
+                handler = handlers[handler_idx % len(handlers)]
+                handler_idx += 1
+
+                # Set context for manual commit
+                ctx = MessageContext(stub, topic, group, msg.offset)
+                token = _current_context.set(ctx)
+
+                try:
+                    handler(msg)
+
+                    # Auto-commit if enabled and not manually committed
+                    if auto_commit and not ctx.committed:
+                        commit()
+
+                except Exception as e:
+                    print(f"Error processing message: {e}")
+                finally:
+                    _current_context.reset(token)
+
+        except grpc.RpcError as e:
+            print(f"Connection lost for {topic}: {e}. Retrying in 5s...")
+            time.sleep(5)
+        except Exception as e:
+            print(f"Unexpected error in consumer {topic}: {e}")
+            time.sleep(5)

pulse/producer.py

@@ -0,0 +1,101 @@
+import json
+import grpc
+from .config import get_config
+from .proto import pulse_pb2, pulse_pb2_grpc
+
+class Producer:
+    def __init__(self, host=None, port=None):
+        config = get_config()
+        self.host = host or config["broker"]["host"]
+        self.port = port or config["broker"]["grpc_port"]
+        self.address = f"{self.host}:{self.port}"
+        
+        self.channel = grpc.insecure_channel(self.address)
+        self.stub = pulse_pb2_grpc.PulseServiceStub(self.channel)
+        
+        self._setup_topics(config)
+
+    def _setup_topics(self, config):
+        for topic_cfg in config.get("topics", []):
+            if topic_cfg.get("create_if_missing", False):
+                name = topic_cfg["name"]
+                t_config = topic_cfg.get("config", {})
+                fifo = t_config.get("fifo", False)
+                retention_bytes = t_config.get("retention_bytes", 0)
+                
+                req = pulse_pb2.CreateTopicRequest(
+                    topic=name,
+                    fifo=fifo,
+                    retention_bytes=retention_bytes
+                )
+                try:
+                    self.stub.CreateTopic(req)
+                except grpc.RpcError:
+                    # Ignore errors (e.g. topic already exists)
+                    pass
+
+    def send(self, topic, payload):
+        """
+        Send a message to a topic.
+        payload can be bytes or a dict (which will be JSON serialized).
+        """
+        headers = {}
+        if isinstance(payload, dict):
+            data = json.dumps(payload).encode("utf-8")
+            headers["payload-type"] = "json"
+        elif isinstance(payload, str):
+            data = payload.encode("utf-8")
+            headers["payload-type"] = "string"
+        elif isinstance(payload, bytes):
+            data = payload
+            headers["payload-type"] = "bytes"
+        else:
+            raise ValueError("Payload must be bytes, str, or dict")
+
+        request = pulse_pb2.PublishRequest(
+            topic=topic,
+            payload=data,
+            headers=headers
+        )
+        
+        try:
+            self.stub.Publish(request)
+        except grpc.RpcError as e:
+            # TODO: Handle retries based on config
+            raise e
+
+    def stream_send(self, message_iterator):
+        """
+        Send a stream of messages to the broker.
+        message_iterator should yield (topic, payload) tuples.
+        """
+        def request_generator():
+            for topic, payload in message_iterator:
+                headers = {}
+                if isinstance(payload, dict):
+                    data = json.dumps(payload).encode("utf-8")
+                    headers["payload-type"] = "json"
+                elif isinstance(payload, str):
+                    data = payload.encode("utf-8")
+                    headers["payload-type"] = "string"
+                elif isinstance(payload, bytes):
+                    data = payload
+                    headers["payload-type"] = "bytes"
+                else:
+                    raise ValueError("Payload must be bytes, str, or dict")
+
+                yield pulse_pb2.PublishRequest(
+                    topic=topic,
+                    payload=data,
+                    headers=headers
+                )
+
+        try:
+            # Consume the response stream (acks)
+            for _ in self.stub.StreamPublish(request_generator()):
+                pass
+        except grpc.RpcError as e:
+            raise e
+
+    def close(self):
+        self.channel.close()

pulse/proto/pulse_pb2.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: pulse.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'pulse.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0bpulse.proto\x12\x08pulse.v1\"\x98\x01\n\x0ePublishRequest\x12\r\n\x05topic\x18\x01 \x01(\t\x12\x0f\n\x07payload\x18\x02 \x01(\x0c\x12\x36\n\x07headers\x18\x03 \x03(\x0b\x32%.pulse.v1.PublishRequest.HeadersEntry\x1a.\n\x0cHeadersEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"-\n\x0fPublishResponse\x12\n\n\x02id\x18\x01 \x01(\t\x12\x0e\n\x06offset\x18\x02 \x01(\x04\"F\n\x0e\x43onsumeRequest\x12\r\n\x05topic\x18\x01 \x01(\t\x12\x15\n\rconsumer_name\x18\x02 \x01(\t\x12\x0e\n\x06offset\x18\x03 \x01(\x04\"\xae\x01\n\x0f\x43onsumeResponse\x12\x0e\n\x06offset\x18\x01 \x01(\x04\x12\x11\n\ttimestamp\x18\x02 \x01(\x03\x12\x0f\n\x07payload\x18\x03 \x01(\x0c\x12\x37\n\x07headers\x18\x04 \x03(\x0b\x32&.pulse.v1.ConsumeResponse.HeadersEntry\x1a.\n\x0cHeadersEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"K\n\x13\x43ommitOffsetRequest\x12\r\n\x05topic\x18\x01 \x01(\t\x12\x15\n\rconsumer_name\x18\x02 \x01(\t\x12\x0e\n\x06offset\x18\x03 \x01(\x04\"\'\n\x14\x43ommitOffsetResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\"\xa9\x01\n\x12\x43reateTopicRequest\x12\r\n\x05topic\x18\x01 \x01(\t\x12\x0c\n\x04\x66ifo\x18\x02 \x01(\x08\x12\x17\n\x0fretention_bytes\x18\x03 \x01(\x03\x12\x16\n\x0eretention_time\x18\x04 \x01(\x03\x12\x17\n\x0f\x66lush_threshold\x18\x05 \x01(\x05\x12\x16\n\x0e\x66lush_interval\x18\x06 \x01(\x03\x12\x14\n\x0csegment_size\x18\x07 \x01(\x03\"&\n\x13\x43reateTopicResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\"\x13\n\x11ListTopicsRequest\"$\n\x12ListTopicsResponse\x12\x0e\n\x06topics\x18\x01 \x03(\t2\xbe\x03\n\x0cPulseService\x12>\n\x07Publish\x12\x18.pulse.v1.PublishRequest\x1a\x19.pulse.v1.PublishResponse\x12H\n\rStreamPublish\x12\x18.pulse.v1.PublishRequest\x1a\x19.pulse.v1.PublishResponse(\x01\x30\x01\x12@\n\x07\x43onsume\x12\x18.pulse.v1.ConsumeRequest\x1a\x19.pulse.v1.ConsumeResponse0\x01\x12M\n\x0c\x43ommitOffset\x12\x1d.pulse.v1.CommitOffsetRequest\x1a\x1e.pulse.v1.CommitOffsetResponse\x12J\n\x0b\x43reateTopic\x12\x1c.pulse.v1.CreateTopicRequest\x1a\x1d.pulse.v1.CreateTopicResponse\x12G\n\nListTopics\x12\x1b.pulse.v1.ListTopicsRequest\x1a\x1c.pulse.v1.ListTopicsResponseB\x11Z\x0fpulse/pkg/protob\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'pulse_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z\017pulse/pkg/proto'
+  _globals['_PUBLISHREQUEST_HEADERSENTRY']._loaded_options = None
+  _globals['_PUBLISHREQUEST_HEADERSENTRY']._serialized_options = b'8\001'
+  _globals['_CONSUMERESPONSE_HEADERSENTRY']._loaded_options = None
+  _globals['_CONSUMERESPONSE_HEADERSENTRY']._serialized_options = b'8\001'
+  _globals['_PUBLISHREQUEST']._serialized_start=26
+  _globals['_PUBLISHREQUEST']._serialized_end=178
+  _globals['_PUBLISHREQUEST_HEADERSENTRY']._serialized_start=132
+  _globals['_PUBLISHREQUEST_HEADERSENTRY']._serialized_end=178
+  _globals['_PUBLISHRESPONSE']._serialized_start=180
+  _globals['_PUBLISHRESPONSE']._serialized_end=225
+  _globals['_CONSUMEREQUEST']._serialized_start=227
+  _globals['_CONSUMEREQUEST']._serialized_end=297
+  _globals['_CONSUMERESPONSE']._serialized_start=300
+  _globals['_CONSUMERESPONSE']._serialized_end=474
+  _globals['_CONSUMERESPONSE_HEADERSENTRY']._serialized_start=132
+  _globals['_CONSUMERESPONSE_HEADERSENTRY']._serialized_end=178
+  _globals['_COMMITOFFSETREQUEST']._serialized_start=476
+  _globals['_COMMITOFFSETREQUEST']._serialized_end=551
+  _globals['_COMMITOFFSETRESPONSE']._serialized_start=553
+  _globals['_COMMITOFFSETRESPONSE']._serialized_end=592
+  _globals['_CREATETOPICREQUEST']._serialized_start=595
+  _globals['_CREATETOPICREQUEST']._serialized_end=764
+  _globals['_CREATETOPICRESPONSE']._serialized_start=766
+  _globals['_CREATETOPICRESPONSE']._serialized_end=804
+  _globals['_LISTTOPICSREQUEST']._serialized_start=806
+  _globals['_LISTTOPICSREQUEST']._serialized_end=825
+  _globals['_LISTTOPICSRESPONSE']._serialized_start=827
+  _globals['_LISTTOPICSRESPONSE']._serialized_end=863
+  _globals['_PULSESERVICE']._serialized_start=866
+  _globals['_PULSESERVICE']._serialized_end=1312
+# @@protoc_insertion_point(module_scope)

pulse/proto/pulse_pb2_grpc.py

@@ -0,0 +1,318 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from . import pulse_pb2 as pulse__pb2
+
+GRPC_GENERATED_VERSION = '1.76.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in pulse_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class PulseServiceStub(object):
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Publish = channel.unary_unary(
+                '/pulse.v1.PulseService/Publish',
+                request_serializer=pulse__pb2.PublishRequest.SerializeToString,
+                response_deserializer=pulse__pb2.PublishResponse.FromString,
+                _registered_method=True)
+        self.StreamPublish = channel.stream_stream(
+                '/pulse.v1.PulseService/StreamPublish',
+                request_serializer=pulse__pb2.PublishRequest.SerializeToString,
+                response_deserializer=pulse__pb2.PublishResponse.FromString,
+                _registered_method=True)
+        self.Consume = channel.unary_stream(
+                '/pulse.v1.PulseService/Consume',
+                request_serializer=pulse__pb2.ConsumeRequest.SerializeToString,
+                response_deserializer=pulse__pb2.ConsumeResponse.FromString,
+                _registered_method=True)
+        self.CommitOffset = channel.unary_unary(
+                '/pulse.v1.PulseService/CommitOffset',
+                request_serializer=pulse__pb2.CommitOffsetRequest.SerializeToString,
+                response_deserializer=pulse__pb2.CommitOffsetResponse.FromString,
+                _registered_method=True)
+        self.CreateTopic = channel.unary_unary(
+                '/pulse.v1.PulseService/CreateTopic',
+                request_serializer=pulse__pb2.CreateTopicRequest.SerializeToString,
+                response_deserializer=pulse__pb2.CreateTopicResponse.FromString,
+                _registered_method=True)
+        self.ListTopics = channel.unary_unary(
+                '/pulse.v1.PulseService/ListTopics',
+                request_serializer=pulse__pb2.ListTopicsRequest.SerializeToString,
+                response_deserializer=pulse__pb2.ListTopicsResponse.FromString,
+                _registered_method=True)
+
+
+class PulseServiceServicer(object):
+    """Missing associated documentation comment in .proto file."""
+
+    def Publish(self, request, context):
+        """Publish sends a message to a topic.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def StreamPublish(self, request_iterator, context):
+        """StreamPublish sends a stream of messages to a topic.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def Consume(self, request, context):
+        """Consume reads messages from a topic as a stream.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def CommitOffset(self, request, context):
+        """CommitOffset commits the offset for a consumer group.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def CreateTopic(self, request, context):
+        """CreateTopic creates a new topic.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def ListTopics(self, request, context):
+        """ListTopics returns a list of all topics.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_PulseServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Publish': grpc.unary_unary_rpc_method_handler(
+                    servicer.Publish,
+                    request_deserializer=pulse__pb2.PublishRequest.FromString,
+                    response_serializer=pulse__pb2.PublishResponse.SerializeToString,
+            ),
+            'StreamPublish': grpc.stream_stream_rpc_method_handler(
+                    servicer.StreamPublish,
+                    request_deserializer=pulse__pb2.PublishRequest.FromString,
+                    response_serializer=pulse__pb2.PublishResponse.SerializeToString,
+            ),
+            'Consume': grpc.unary_stream_rpc_method_handler(
+                    servicer.Consume,
+                    request_deserializer=pulse__pb2.ConsumeRequest.FromString,
+                    response_serializer=pulse__pb2.ConsumeResponse.SerializeToString,
+            ),
+            'CommitOffset': grpc.unary_unary_rpc_method_handler(
+                    servicer.CommitOffset,
+                    request_deserializer=pulse__pb2.CommitOffsetRequest.FromString,
+                    response_serializer=pulse__pb2.CommitOffsetResponse.SerializeToString,
+            ),
+            'CreateTopic': grpc.unary_unary_rpc_method_handler(
+                    servicer.CreateTopic,
+                    request_deserializer=pulse__pb2.CreateTopicRequest.FromString,
+                    response_serializer=pulse__pb2.CreateTopicResponse.SerializeToString,
+            ),
+            'ListTopics': grpc.unary_unary_rpc_method_handler(
+                    servicer.ListTopics,
+                    request_deserializer=pulse__pb2.ListTopicsRequest.FromString,
+                    response_serializer=pulse__pb2.ListTopicsResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'pulse.v1.PulseService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('pulse.v1.PulseService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class PulseService(object):
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Publish(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/pulse.v1.PulseService/Publish',
+            pulse__pb2.PublishRequest.SerializeToString,
+            pulse__pb2.PublishResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def StreamPublish(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/pulse.v1.PulseService/StreamPublish',
+            pulse__pb2.PublishRequest.SerializeToString,
+            pulse__pb2.PublishResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def Consume(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/pulse.v1.PulseService/Consume',
+            pulse__pb2.ConsumeRequest.SerializeToString,
+            pulse__pb2.ConsumeResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def CommitOffset(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/pulse.v1.PulseService/CommitOffset',
+            pulse__pb2.CommitOffsetRequest.SerializeToString,
+            pulse__pb2.CommitOffsetResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def CreateTopic(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/pulse.v1.PulseService/CreateTopic',
+            pulse__pb2.CreateTopicRequest.SerializeToString,
+            pulse__pb2.CreateTopicResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def ListTopics(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/pulse.v1.PulseService/ListTopics',
+            pulse__pb2.ListTopicsRequest.SerializeToString,
+            pulse__pb2.ListTopicsResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

pulse/proto_manager.py

@@ -0,0 +1,59 @@
+import os
+import sys
+import urllib.request
+import re
+
+def ensure_proto(host="localhost", port=5555):
+    try:
+        from grpc_tools import protoc
+    except ImportError:
+        return
+
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    proto_dir = os.path.join(current_dir, "proto")
+    proto_file = os.path.join(proto_dir, "pulse.proto")
+    
+    # Try to download
+    try:
+        url = f"http://{host}:{port}/proto"
+        # Short timeout to avoid blocking startup
+        with urllib.request.urlopen(url, timeout=0.5) as response:
+            content = response.read()
+            
+        if not os.path.exists(proto_dir):
+            os.makedirs(proto_dir)
+            
+        # Check if content changed? For now just overwrite.
+        with open(proto_file, "wb") as f:
+            f.write(content)
+            
+        # Compile
+        cmd = [
+            "grpc_tools.protoc",
+            f"-I{proto_dir}",
+            f"--python_out={proto_dir}",
+            f"--grpc_python_out={proto_dir}",
+            "pulse.proto"
+        ]
+        
+        # We run from current_dir to avoid path issues?
+        # Actually, let's just pass the args.
+        exit_code = protoc.main(cmd)
+        
+        if exit_code == 0:
+            # Fix imports in pulse_pb2_grpc.py to use relative import
+            grpc_file = os.path.join(proto_dir, "pulse_pb2_grpc.py")
+            if os.path.exists(grpc_file):
+                with open(grpc_file, "r") as f:
+                    content = f.read()
+                
+                # Replace 'import pulse_pb2' with 'from . import pulse_pb2'
+                new_content = re.sub(r'^import pulse_pb2', 'from . import pulse_pb2', content, flags=re.MULTILINE)
+                
+                if new_content != content:
+                    with open(grpc_file, "w") as f:
+                        f.write(new_content)
+                        
+    except Exception:
+        # Ignore errors (server down, etc)
+        pass

pulse_broker-1.0.8.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: pulse-broker
+Version: 1.0.8
+Summary: Python SDK for Pulse Broker
+Home-page: https://github.com/marcosrosa/pulse
+Author: Marcos Rosa
+Author-email: marcos@example.com
+Project-URL: Bug Tracker, https://github.com/marcosrosa/pulse/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.50.0
+Requires-Dist: protobuf>=4.21.0
+Requires-Dist: pyyaml>=6.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Pulse Python SDK
+
+Official Python client for [Pulse Broker](https://github.com/marcosrosa/pulse).
+
+## Installation
+
+```bash
+pip install pulse-broker
+```
+
+## Configuration
+
+The SDK looks for a `pulse.yaml` (or `pulse.yml`) file in your project root. If not found, it defaults to `localhost:5555` (HTTP) and `localhost:5556` (gRPC).
+
+### Example `pulse.yaml`
+
+```yaml
+# Connection Settings
+broker:
+  host: "localhost"
+  http_port: 5555
+  grpc_port: 5556
+  timeout_ms: 5000
+
+# Client Defaults
+client:
+  id: "my-python-app"
+  auto_commit: true       # Automatically commit offsets after successful processing
+  max_retries: 3
+
+# Topic Configuration
+topics:
+  - name: "events"
+    create_if_missing: true
+    config:
+      fifo: false
+      retention_bytes: 1073741824  # 1GB
+    consume:
+      auto_commit: true
+
+  - name: "transactions"
+    create_if_missing: true
+    config:
+      fifo: true
+    consume:
+      auto_commit: false  # Manual commit required
+
+  - name: "logs"
+    create_if_missing: true
+    config:
+      fifo: false
+    consume:
+      auto_commit: true
+```
+
+## Usage
+
+### Producer
+
+You can send dictionaries (automatically serialized to JSON) or raw bytes.
+
+```python
+from pulse import Producer
+
+# Initialize (uses pulse.yaml or defaults)
+# You can override settings: Producer(host="10.0.0.1", port=9090)
+producer = Producer()
+
+# Send JSON
+producer.send("events", {"type": "user_created", "id": 123})
+
+# Send Bytes
+producer.send("logs", b"raw log line")
+
+producer.close()
+```
+
+### Consumer
+
+Use the `@consumer` decorator to register message handlers.
+
+```python
+from pulse import consumer, commit, run
+
+# Simple Consumer (uses auto_commit from config)
+@consumer("events")
+def handle_event(msg):
+    print(f"Received event: {msg.payload}")
+    # msg.payload is a dict if JSON, else bytes
+
+# Manual Commit Consumer
+# Override config params directly in the decorator if needed
+@consumer("transactions", auto_commit=False)
+def handle_transaction(msg):
+    try:
+        process_payment(msg.payload)
+        commit()  # Manually commit offset
+        print(f"Processed transaction {msg.offset}")
+    except Exception as e:
+        print(f"Failed to process: {e}")
+        # Do not commit, message will be redelivered on restart/rebalance
+
+if __name__ == "__main__":
+    print("Starting consumers...")
+    run()  # Blocks and runs all registered consumers
+```

pulse_broker-1.0.8.dist-info/RECORD

@@ -0,0 +1,14 @@
+pulse/__init__.py,sha256=4_52hPziGhNe8OmYHpsC8Ds600AB2BqHNu33B2HxxxE,434
+pulse/config.py,sha256=Tj33DqGHBWGtwD-i1OY6g2zg7EbcpN7ZYzxxHHu7mGY,1463
+pulse/consumer.py,sha256=ptI_Ct9wlQSD5TR69rGM_EyMDkURNpROuQd_StUiJMI,8659
+pulse/producer.py,sha256=puFFS5a-_tlJKEsoMjnaPApE6-3AW_CrC41uSaA6CXw,3519
+pulse/proto_manager.py,sha256=EWCHAP9SnrCsqIh3z7vlMtCgmGabGvECd9cp-DJWUbk,1978
+pulse/proto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pulse/proto/pulse_pb2.py,sha256=fozRHf0Nc0ow0m6Js9x_UwpWUSB31P40rcnl1W1AjUw,5093
+pulse/proto/pulse_pb2_grpc.py,sha256=BpsOTT2QLMBk50bzoJuW9AIOuLzSteQhpTRzPu8XSfc,11808
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_pulse.py,sha256=kfOc45I3_8u4ahcDV662VFm2ptMEGl4HrBjv8cqQoHU,2339
+pulse_broker-1.0.8.dist-info/METADATA,sha256=XvyoxEft2WJtHavaSkA8nlyWDh1VPC0FOL7CgHSk67s,3149
+pulse_broker-1.0.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pulse_broker-1.0.8.dist-info/top_level.txt,sha256=zkkZiZZQSAp3NX32LmPIvlprjgl4x0qokPGr3fQSmno,12
+pulse_broker-1.0.8.dist-info/RECORD,,

pulse_broker-1.0.8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pulse_broker-1.0.8.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+pulse
+tests

tests/test_pulse.py

@@ -0,0 +1,76 @@
+import pytest
+from unittest.mock import MagicMock, patch, ANY
+import pulse
+from pulse.proto import pulse_pb2
+
+# --- Producer Tests ---
+
+def test_producer_init():
+    with patch('pulse.producer.grpc.insecure_channel') as mock_channel:
+        p = pulse.Producer(host="myhost", port=9999)
+        mock_channel.assert_called_with("myhost:9999")
+
+def test_producer_send_dict():
+    with patch('pulse.producer.grpc.insecure_channel'):
+        mock_stub = MagicMock()
+        with patch('pulse.producer.pulse_pb2_grpc.PulseServiceStub', return_value=mock_stub):
+            p = pulse.Producer()
+            p.send("topic1", {"key": "value"})
+            
+            mock_stub.Publish.assert_called_once()
+            args, _ = mock_stub.Publish.call_args
+            req = args[0]
+            assert req.topic == "topic1"
+            assert req.payload == b'{"key": "value"}'
+
+def test_producer_send_bytes():
+    with patch('pulse.producer.grpc.insecure_channel'):
+        mock_stub = MagicMock()
+        with patch('pulse.producer.pulse_pb2_grpc.PulseServiceStub', return_value=mock_stub):
+            p = pulse.Producer()
+            p.send("topic1", b"raw-data")
+            
+            args, _ = mock_stub.Publish.call_args
+            req = args[0]
+            assert req.payload == b"raw-data"
+
+# --- Consumer Tests ---
+
+def test_consumer_decorator_registration():
+    # Clear consumers
+    from pulse.consumer import _consumers
+    _consumers.clear()
+    
+    @pulse.consumer("test-topic", consumer_group="my-group")
+    def my_handler(msg):
+        pass
+    
+    assert len(_consumers) == 1
+    c = _consumers[0]
+    assert c["topic"] == "test-topic"
+    assert c["group"] == "my-group"
+    assert c["handler"] == my_handler
+
+def test_commit_outside_context():
+    with pytest.raises(RuntimeError):
+        pulse.commit()
+
+# --- Config Tests ---
+
+def test_load_config_defaults():
+    cfg = pulse.load_config(path="nonexistent")
+    assert cfg["broker"]["http_port"] == 5555
+
+def test_load_config_file(tmp_path):
+    f = tmp_path / "pulse.yaml"
+    f.write_text("""
+broker:
+  http_port: 8080
+client:
+  id: "test-client"
+""")
+    cfg = pulse.load_config(path=str(f))
+    assert cfg["broker"]["http_port"] == 8080
+    assert cfg["client"]["id"] == "test-client"
+    # Check default preserved
+    assert cfg["broker"]["grpc_port"] == 5556