2026-04-10 23:20:41 -04:00
---
layout: default
title: "Pub/Sub Altyapı ı
parent: "Turkish (Beta)"
---
2026-04-11 01:08:44 +00:00
# Pub/Sub Altyapı ı
2026-04-10 23:20:41 -04:00
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
2026-04-11 01:08:44 +00:00
## Genel Bakı
Bu belge, TrustGraph kod tabanı ı ı ı ı ı ı ı ı ı ı ı ı ı ı
## Mevcut Durum: Pulsar Entegrasyon Noktaları
### 1. Doğrudan Pulsar İstemci Kullanı ı
**Konum:** `trustgraph-flow/trustgraph/gateway/service.py`
API ağ geçidi, doğrudan Pulsar istemcisini içe aktarı
**Satı `import pulsar`
**Satı `pulsar.Client()` 'ı ı `pulsar.AuthenticationToken()` ile birlikte
**Satı ı ı ı ı ı
**Satı `--pulsar-host` , `--pulsar-api-key` ve `--pulsar-listener` için CLI argümanları
**Satı `pulsar_client` 'ı `ConfigReceiver` ve `DispatcherManager` 'ye geçirir
Bu, bir soyutlama katmanı ı ı
### 2. Temel İşlemci Çerçevesi
**Konum:** `trustgraph-base/trustgraph/base/async_processor.py`
Tüm işlemciler için temel sı ı ı ı
**Satı `import _pulsar` (istisna işleme için)
**Satı `from . pubsub import PulsarClient`
**Satı `pulsar_client_object = PulsarClient(**params)` oluşturur
**Satı `pulsar_host` ve `pulsar_client` 'i ortaya koyan özellikler
**Satı `add_args()` , CLI argümanları `PulsarClient.add_args(parser)` 'i çağı ı
**Satı `_pulsar.Interrupted` için istisna işleme
Tüm işlemciler `AsyncProcessor` 'dan türetildiği için, bu merkezi bir entegrasyon noktası ı
### 3. Tüketici Soyutlaması
**Konum:** `trustgraph-base/trustgraph/base/consumer.py`
Kuyruklardan mesajlar tüketir ve işleyici fonksiyonları ı ı ı
**Pulsar içe aktarmaları
**Satı `from pulsar.schema import JsonSchema`
**Satı `import pulsar`
**Satı `import _pulsar`
**Pulsar'a özgü kullanı
**Satı `pulsar.InitialPosition.Earliest` / `pulsar.InitialPosition.Latest`
**Satı `JsonSchema(self.schema)` sarmalayı ı ı
**Satı `pulsar.ConsumerType.Shared`
**Satı `self.client.subscribe()`
**Satı `consumer.unsubscribe()` ve `consumer.close()` yöntemleri
**Satı `_pulsar.Timeout` istisnası
**Satı `consumer.acknowledge()` / `consumer.negative_acknowledge()`
**Belge dosyası `trustgraph-base/trustgraph/base/consumer_spec.py`
**Satı `processor.pulsar_client` 'a referans
### 4. Yayı ı ı
**Konum:** `trustgraph-base/trustgraph/base/producer.py`
Kuyruklara mesaj gönderir:
**Pulsar içe aktarmaları
**Satı `from pulsar.schema import JsonSchema`
**Pulsar'a özgü kullanı
**Satı `JsonSchema(self.schema)` sarmalayı ı ı
**Satı `self.client.create_producer()`
**Satı `producer.close()` yöntemi
**Satı `producer.send()`
**Belge dosyası `trustgraph-base/trustgraph/base/producer_spec.py`
**Satı `processor.pulsar_client` 'a referans
### 5. Yayı ı ı
**Konum:** `trustgraph-base/trustgraph/base/publisher.py`
Kuyruklu tamponlama ile asenkron mesaj yayı
**Pulsar içe aktarmaları
**Satı `from pulsar.schema import JsonSchema`
**Satı `import pulsar`
**Pulsar'a özgü kullanı
**Satı `JsonSchema(self.schema)` sarmalayı ı ı
**Satı `self.client.create_producer()`
**Satı ı `producer.send()`
**Satı `producer.flush()` ve `producer.close()` yöntemleri
### 6. Abonelik Soyutlaması
**Konum:** `trustgraph-base/trustgraph/base/subscriber.py`
Kuyruklardan çoklu alı ı ı ı ı
**Pulsar importları
**6. Satı `from pulsar.schema import JsonSchema`
**8. Satı `import _pulsar`
**Pulsar'a özgü kullanı
**55. Satı `JsonSchema(self.schema)` wrapper
**57. Satı `self.client.subscribe(**subscribe_args)`
**101, 136, 160, 167-172. Satı ı `_pulsar.Timeout` , `_pulsar.InvalidConfiguration` , `_pulsar.AlreadyClosed`
**159, 166, 170. Satı ı `negative_acknowledge()` , `unsubscribe()` , `close()`
**247, 251. Satı ı `acknowledge()` , `negative_acknowledge()`
**Spec dosyası `trustgraph-base/trustgraph/base/subscriber_spec.py`
**19. Satı `processor.pulsar_client` 'a referans
### 7. Şema Sistemi (Heart of Darkness)
**Konum:** `trustgraph-base/trustgraph/schema/`
Sistemdeki her mesaj şeması ı ı ı ı
**Temel öğeler:** `schema/core/primitives.py`
**2. Satı `from pulsar.schema import Record, String, Boolean, Array, Integer`
Tüm şemalar, Pulsar'ı `Record` temel sı ı ı
Tüm alan türleri Pulsar türleridir: `String()` , `Integer()` , `Boolean()` , `Array()` , `Map()` , `Double()`
**Örnek şemalar:**
`schema/services/llm.py` (2. Satı `from pulsar.schema import Record, String, Array, Double, Integer, Boolean`
`schema/services/config.py` (2. Satı `from pulsar.schema import Record, Bytes, String, Boolean, Array, Map, Integer`
**Konu adlandı ı `schema/core/topic.py`
**2-3. Satı ı `{kind}://{tenant}/{namespace}/{topic}`
Bu URI yapı ı `persistent://tg/flow/config` )
**Etki:**
Kod tabanı ı ı ı ı ı ı
Bu, aşağı ı ı ı ı ı ı ı ı ı
Şema tanı ı ı ı ı ı ı
## Özet
### Kategoriye Göre Pulsar Bağı ı ı ı
1. **İstem oluşturma:**
Doğrudan: `gateway/service.py`
Soyutlanmı `async_processor.py` → `pubsub.py` (PulsarClient)
2. **Mesaj taşı
Tüketici: `consumer.py` , `consumer_spec.py`
Üretici: `producer.py` , `producer_spec.py`
Yayı ı `publisher.py`
Abonelik: `subscriber.py` , `subscriber_spec.py`
3. **Şema sistemi:**
Temel türler: `schema/core/primitives.py`
Tüm hizmet şemaları `schema/services/*.py`
Konu adlandı ı `schema/core/topic.py`
4. **Gereken Pulsar'a özgü kavramlar:**
Konuya dayalı
Şema sistemi (Kayı
Paylaşı ı
Mesaj onayı
Tüketici konumlandı ı
Mesaj özellikleri
Başlangı ı
Parçalama desteği
Kalı ı ı ı
### Yeniden Düzenleme Zorlukları
İyi haber: Soyutlama katmanı ı ı
Zorluklar:
1. **Şema sisteminin yaygı ı ı Her mesaj tanı ı `pulsar.schema.Record` ve Pulsar alan türlerini kullanı
2. **Pulsar'a özgü numaralandı `InitialPosition` , `ConsumerType`
3. **Pulsar istisnaları `_pulsar.Timeout` , `_pulsar.Interrupted` , `_pulsar.InvalidConfiguration` , `_pulsar.AlreadyClosed`
4. **Metot imzaları `acknowledge()` , `negative_acknowledge()` , `subscribe()` , `create_producer()` , vb.
5. **Konu URI formatı Pulsar'ı `kind://tenant/namespace/topic` yapı ı
### Sonraki Adı
Yayı ı ı ı ı ı ı ı ı
1. İstem/şema sistemi için bir soyutlama arayüzü oluşturun.
2. Pulsar'a özgü numaralandı ı ı ı
3. Şema sargı ı ı ı
4. Arayüzü hem Pulsar hem de alternatif sistemler (Kafka, RabbitMQ, Redis Streams, vb.) için uygulayı
5. `pubsub.py` 'ı ı ı ı ı
6. Mevcut dağı ı ı
## Yaklaşı ı ı ı ı
### Temel Bilgi
**Şema sistemi**, en derin entegrasyon noktası ı ı ı
### Strateji: Minimum Bozulma ile Adaptörler
**1. Pulsar şemaları ı
Tüm şema tanı ı ı ı
Şemalar, dahili olarak `pulsar.schema.Record` olarak kalı
Adaptörleri, kendi kodumuz ile yayı ı ı ı ı
**2. Bir yayı ı
```
┌─────────────────────────────────────┐
│ Existing Code (unchanged) │
│ - Uses Pulsar schemas internally │
│ - Consumer/Producer/Publisher │
└──────────────┬──────────────────────┘
│
┌──────────────┴──────────────────────┐
│ PubSubFactory (configurable) │
│ - Creates backend-specific client │
└──────────────┬──────────────────────┘
│
┌──────┴──────┐
│ │
┌───────▼─────┐ ┌────▼─────────┐
│ PulsarAdapter│ │ KafkaAdapter │ etc...
│ (passthrough)│ │ (translates) │
└──────────────┘ └──────────────┘
```
**3. Soyut arayüzleri tanı ı
`PubSubClient` - istemci bağlantı ı
`PubSubProducer` - mesaj gönderme
`PubSubConsumer` - mesaj alma
`SchemaAdapter` - Pulsar şemaları ı ı
**4. Uygulama detayları
**Pulsar adaptörü için:** Neredeyse doğrudan geçiş, minimum çeviri
**Diğer arka uçlar için** (Kafka, RabbitMQ, vb.):
Pulsar Kayı
Aşağı ı
`InitialPosition.Earliest/Latest` → Kafka'nı
`acknowledge()` → Kafka'nı
`negative_acknowledge()` → Yeniden kuyruklama veya DLQ deseni
Konu URI'leri → Arka uç özel konu adları
### Analiz
**Artı ı
✅ Mevcut hizmetlerde minimum kod değişikliği
✅ Şemalar olduğu gibi kalı ı
✅ Aşamalı
✅ Pulsar kullanı ı ı
✅ Yeni arka uçlar adaptörler aracı ı ı
**Eksileri:**
⚠️ Hala Pulsar bağı ı ı ı ı ı ı
⚠️ Kavramları ı
### Alternatif Düşünce
Bir **TrustGraph şema sistemi** oluşturun; bu sistem, pub/sub'dan bağı ı ı ı ı ı ı ı ı ı ı
### Taslak 1 için Öneri
**Adaptör yaklaşı ı ı
1. Pratik bir yaklaşı ı ı ı
2. Minimum riskle kavramı ı
3. Gerekirse daha sonra yerel bir şema sistemine dönüştürülebilir
4. Yapı ı ı ı ı
## Yaklaşı ı ı ı
### Temel Kavram
Python **dataclass'ları tarafsı ı ı ı ı ı ı ı ı ı ı ı
### Fabrika Seviyesinde Şema Çok Biçimliliği
Pulsar şemaları ı **her arka uç, standart Python dataclass'ları ı .
### Yayı ı ı ı
```python
# 1. Get the configured backend from factory
pubsub = get_pubsub() # Returns PulsarBackend, MQTTBackend, etc.
# 2. Get schema class from the backend
# (Can be imported directly - backend-agnostic)
from trustgraph.schema.services.llm import TextCompletionRequest
# 3. Create a producer/publisher for a specific topic
producer = pubsub.create_producer(
topic="text-completion-requests",
schema=TextCompletionRequest # Tells backend what schema to use
)
# 4. Create message instances (same API regardless of backend)
request = TextCompletionRequest(
system="You are helpful",
prompt="Hello world",
streaming=False
)
# 5. Send the message
producer.send(request) # Backend serializes appropriately
```
### Tüketici Akı ı
```python
# 1. Get the configured backend
pubsub = get_pubsub()
# 2. Create a consumer
consumer = pubsub.subscribe(
topic="text-completion-requests",
schema=TextCompletionRequest # Tells backend how to deserialize
)
# 3. Receive and deserialize
msg = consumer.receive()
request = msg.value() # Returns TextCompletionRequest dataclass instance
# 4. Use the data (type-safe access)
print(request.system) # "You are helpful"
print(request.prompt) # "Hello world"
print(request.streaming) # False
```
### Sahne Arkası
**Pulsar arka ucu için:**
`create_producer()` → JSON şeması ı
`send(request)` → veri sı ı ı ı ı
`receive()` → Pulsar mesajı ı ı ı ı ı
**MQTT arka ucu için:**
`create_producer()` → MQTT aracı ı ı ı
`send(request)` → veri sı ı ı ı ı
`receive()` → MQTT konusuna abone olur, JSON'ı ı ı ı
**Kafka arka ucu için:**
`create_producer()` → Kafka üreticisini oluşturur, gerekirse Avro şeması ı
`send(request)` → veri sı ı ı ı ı
`receive()` → Kafka mesajı ı ı ı ı ı
### Temel Tasarı ı
1. **Şema nesnesi oluşturma** : Veri sı ı ı `TextCompletionRequest(...)` ), arka uçtan bağı ı ı ı
2. **Arka uç, kodlamayı : Her arka uç, veri sı ı ı ı ı ı
3. **Oluşturma sı ı ı ı : Üretici/tüketici oluştururken, şema türünü belirtirsiniz.
4. **Tür güvenliği korunur** : Doğru bir `TextCompletionRequest` nesnesi alı ı ı
5. **Arka uç sı ı ı ı : Uygulama kodu, arka uçla ilgili özel kütüphaneleri asla içe aktarmaz.
### Örnek Dönüşüm
**Mevcut (Pulsar'a özel):**
```python
# schema/services/llm.py
from pulsar.schema import Record, String, Boolean, Integer
class TextCompletionRequest(Record):
system = String()
prompt = String()
streaming = Boolean()
```
**Yeni (Arka uçtan bağı ı
```python
# schema/services/llm.py
from dataclasses import dataclass
@dataclass
class TextCompletionRequest:
system: str
prompt: str
streaming: bool = False
```
### Arka Uç Entegrasyonu
Her arka uç, veri sı ı ı ı
**Pulsar arka ucu:**
Veri sı ı ı `pulsar.schema.Record` sı ı ı
Veya veri sı ı ı ı ı ı ı ı
Mevcut Pulsar kurulumları
**MQTT/Redis arka ucu:**
Veri sı ı ı
`dataclasses.asdict()` / `from_dict()` kullanı
Hafif, şema kayı
**Kafka arka ucu:**
Veri sı ı ı ı ı ı
Confluent'ı ı ı
Şema evrimi desteğiyle tür güvenli serileştirme
### Mimari
```
┌─────────────────────────────────────┐
│ Application Code │
│ - Uses dataclass schemas │
│ - Backend-agnostic │
└──────────────┬──────────────────────┘
│
┌──────────────┴──────────────────────┐
│ PubSubFactory (configurable) │
│ - get_pubsub() returns backend │
└──────────────┬──────────────────────┘
│
┌──────┴──────┐
│ │
┌───────▼─────────┐ ┌────▼──────────────┐
│ PulsarBackend │ │ MQTTBackend │
│ - JSON schema │ │ - JSON serialize │
│ - or dynamic │ │ - Simple queues │
│ Record gen │ │ │
└─────────────────┘ └───────────────────┘
```
### Uygulama Detayları
**1. Şema tanı ı ı
`str` , `int` , `bool` , `float` temel veri tipleri için
`list[T]` diziler için
`dict[str, T]` haritalar için
Karmaşı
**2. Her arka uç şunları
Serileştirici: `dataclass → bytes/wire format`
Seri dı ı ı `bytes/wire format → dataclass`
Şema kaydı
**3. Tüketici/Üretici soyutlaması
Zaten mevcut (consumer.py, producer.py)
Arka uç tarafı ı ı
Doğrudan Pulsar içe aktarmaları ı ı ı
**4. Tür eşlemeleri:**
Pulsar `String()` → Python `str`
Pulsar `Integer()` → Python `int`
Pulsar `Boolean()` → Python `bool`
Pulsar `Array(T)` → Python `list[T]`
Pulsar `Map(K, V)` → Python `dict[K, V]`
Pulsar `Double()` → Python `float`
Pulsar `Bytes()` → Python `bytes`
### Geçiş Yolu
1. `trustgraph/schema/` içindeki tüm şemaları **dataclass versiyonları ı
2. Arka uç tarafı ı ı **arka uç sı ı ı ı ı ı
3. JSON şeması ı ı ı **PulsarBackend'i uygulayı
4. **Mevcut dağı ı
5. Gerekirse **yeni arka uçlar ekleyin (MQTT, Kafka, Redis, vb.)**
6. Şema dosyaları **Pulsar içe aktarmaları ı ı ı
### Avantajlar
✅ **Şema tanı ı ı ı ı ı ı
✅ **Standart Python** - anlaşı ı ı ı
✅ **Modern araçlar** - mypy, IDE otomatik tamamlama, lint araçları ı ı
✅ **Arka uç odaklı - her arka uç yerel seri dı ı ı
✅ **Çeviri ek yükü yok** - doğrudan seri dı
✅ **Tür güvenliği** - uygun türlere sahip gerçek nesneler
✅ **Kolay doğrulama** - gerekirse Pydantic kullanı
### Zorluklar & Çözümler
**Zorluk:** Pulsar'ı `Record` 'ı ı ı ı
**Çözüm:** Gerekirse doğrulama için Pydantic dataclass'ları ı ı `__post_init__` ile Python 3.10+ dataclass özelliklerini kullanı
**Zorluk:** Bazı `Bytes` türü)
**Çözüm:** Bu türü dataclass'ta `bytes` türüne eşleyin, arka uç uygun şekilde kodlamayı
**Zorluk:** Konu adlandı ı `persistent://tenant/namespace/topic` )
**Çözüm:** Şema tanı ı ı ı ı
**Zorluk:** Şema evrimi ve sürüm oluşturma
**Çözüm:** Her arka uç, yeteneklerine göre bunu işler (Pulsar şema sürümleri, Kafka şema kaydı
**Zorluk:** İç içe karmaşı
**Çözüm:** İç içe dataclass'ları ı ı ı
### Tasarı ı
1. **Basit dataclass'lar mı
✅ **Karar: Basit Python dataclass'ları ı
Daha basit, ek bağı ı ı
Uygulamada doğrulama gerekli değil
Anlaşı ı ı ı
2. **Şema evrimi:**
✅ **Karar: Herhangi bir sürüm oluşturma mekanizması
Şemalar kararlı
Güncellemeler genellikle yeni alanlar ekler (geriye dönük uyumlu)
Arka uçlar, yeteneklerine göre şema evrimini işler
3. **Geriye dönük uyumluluk:**
✅ **Karar: Ana sürüm değişikliği, geriye dönük uyumluluk gerekli değil**
Bu, bir kopma değişikliği olacak ve geçiş talimatları
Temiz bir kopma, daha iyi bir tasarı
Mevcut dağı ı ı ı
4. **İç içe türler ve karmaşı ı
✅ **Karar: İç içe dataclass'ları ı
Python dataclass'ları
Diziler için `list[T]` , haritalar için `dict[K, V]`
Arka uçlar yinelemeli olarak seri dı ı
Örnek:
```python
@dataclass
class Value:
value: str
is_uri: bool
@dataclass
class Triple:
s: Value # Nested dataclass
p: Value
o: Value
@dataclass
class GraphQuery:
triples: list[Triple] # Array of nested dataclasses
metadata: dict[str, str]
```
5. **Varsayı ı
✅ **Karar: Gerekli, varsayı ı ı
Gerekli alanlar: Herhangi bir varsayı
Varsayı ı ı
Tamamen isteğe bağlı `T | None = None` , `None` olduğunda serileştirmeden çı ı ı
Örnek:
```python
@dataclass
class TextCompletionRequest:
system: str # Required, no default
prompt: str # Required, no default
streaming: bool = False # Optional with default value
metadata: dict | None = None # Truly optional, can be absent
```
**Önemli serileştirme kuralları
`metadata = None` olduğunda:
```json
{
"system": "...",
"prompt": "...",
"streaming": false
// metadata field NOT PRESENT
}
```
`metadata = {}` (açı
```json
{
"system": "...",
"prompt": "...",
"streaming": false,
"metadata": {} // Field PRESENT but empty
}
```
**Temel ayrı
`None` → JSON'da bulunmayan alan (serileştirilmiyor)
Boş değer (`{}` , `[]` , `""` ) → alan, boş bir değerle mevcut
Bu, anlamsal olarak önemlidir: "sağlanmadı ı
Serileştirme arka uçları `None` alanları ı ı ı `null` olarak kodlamamalı ı
## Yaklaşı ı ı
### Genel Kuyruk Adlandı ı
Arka uçlara özgü kuyruk adları ı ı
**Format:** `{qos}/{tenant}/{namespace}/{queue-name}`
Nerede:
`qos` : Hizmet kalitesi seviyesi
`q0` = en iyi çaba (ateşle ve unut, onay yok)
`q1` = en az bir kez (onay gerektirir)
`q2` = tam olarak bir kez (iki aşamalı
`tenant` : Çok kiracı ı ı ı ı
`namespace` : Kiracı ı
`queue-name` : Gerçek kuyruk/konu adı
**Örnekler:**
```
q1/tg/flow/text-completion-requests
q2/tg/config/config-push
q0/tg/metrics/stats
```
### Arka Uç Konu Eşlemesi
Her arka uç, genel formatı ı
**Pulsar Arka Ucu:**
```python
def map_topic(self, generic_topic: str) -> str:
# Parse: q1/tg/flow/text-completion-requests
qos, tenant, namespace, queue = generic_topic.split('/', 3)
# Map QoS to persistence
persistence = 'persistent' if qos in ['q1', 'q2'] else 'non-persistent'
# Return Pulsar URI: persistent://tg/flow/text-completion-requests
return f"{persistence}://{tenant}/{namespace}/{queue}"
```
**MQTT Altyapı ı
```python
def map_topic(self, generic_topic: str) -> tuple[str, int]:
# Parse: q1/tg/flow/text-completion-requests
qos, tenant, namespace, queue = generic_topic.split('/', 3)
# Map QoS level
qos_level = {'q0': 0, 'q1': 1, 'q2': 2}[qos]
# Build MQTT topic including tenant/namespace for proper namespacing
mqtt_topic = f"{tenant}/{namespace}/{queue}"
return mqtt_topic, qos_level
```
### Güncellenmiş Konu Yardı ı
```python
# schema/core/topic.py
def topic(queue_name, qos='q1', tenant='tg', namespace='flow'):
"""
Create a generic topic identifier that can be mapped by backends.
Args:
queue_name: The queue/topic name
qos: Quality of service
- 'q0' = best-effort (no ack)
- 'q1' = at-least-once (ack required)
- 'q2' = exactly-once (two-phase ack)
tenant: Tenant identifier for multi-tenancy
namespace: Namespace within tenant
Returns:
Generic topic string: qos/tenant/namespace/queue_name
Examples:
topic('my-queue') # q1/tg/flow/my-queue
topic('config', qos='q2', namespace='config') # q2/tg/config/config
"""
return f"{qos}/{tenant}/{namespace}/{queue_name}"
```
### Yapı ı
**Komut Satı ı ı
```python
# In base/async_processor.py - add_args() method
@staticmethod
def add_args(parser):
# Pub/sub backend selection
parser.add_argument(
'--pubsub-backend',
default=os.getenv('PUBSUB_BACKEND', 'pulsar'),
choices=['pulsar', 'mqtt'],
help='Pub/sub backend (default: pulsar, env: PUBSUB_BACKEND)'
)
# Pulsar-specific configuration
parser.add_argument(
'--pulsar-host',
default=os.getenv('PULSAR_HOST', 'pulsar://localhost:6650'),
help='Pulsar host (default: pulsar://localhost:6650, env: PULSAR_HOST)'
)
parser.add_argument(
'--pulsar-api-key',
default=os.getenv('PULSAR_API_KEY', None),
help='Pulsar API key (env: PULSAR_API_KEY)'
)
parser.add_argument(
'--pulsar-listener',
default=os.getenv('PULSAR_LISTENER', None),
help='Pulsar listener name (env: PULSAR_LISTENER)'
)
# MQTT-specific configuration
parser.add_argument(
'--mqtt-host',
default=os.getenv('MQTT_HOST', 'localhost'),
help='MQTT broker host (default: localhost, env: MQTT_HOST)'
)
parser.add_argument(
'--mqtt-port',
type=int,
default=int(os.getenv('MQTT_PORT', '1883')),
help='MQTT broker port (default: 1883, env: MQTT_PORT)'
)
parser.add_argument(
'--mqtt-username',
default=os.getenv('MQTT_USERNAME', None),
help='MQTT username (env: MQTT_USERNAME)'
)
parser.add_argument(
'--mqtt-password',
default=os.getenv('MQTT_PASSWORD', None),
help='MQTT password (env: MQTT_PASSWORD)'
)
```
**Fabrika Fonksiyonu:**
```python
# In base/pubsub.py or base/pubsub_factory.py
def get_pubsub(**config) -> PubSubBackend:
"""
Create and return a pub/sub backend based on configuration.
Args:
config: Configuration dict from command-line args
Must include 'pubsub_backend' key
Returns:
Backend instance (PulsarBackend, MQTTBackend, etc.)
"""
backend_type = config.get('pubsub_backend', 'pulsar')
if backend_type == 'pulsar':
return PulsarBackend(
host=config.get('pulsar_host'),
api_key=config.get('pulsar_api_key'),
listener=config.get('pulsar_listener'),
)
elif backend_type == 'mqtt':
return MQTTBackend(
host=config.get('mqtt_host'),
port=config.get('mqtt_port'),
username=config.get('mqtt_username'),
password=config.get('mqtt_password'),
)
else:
raise ValueError(f"Unknown pub/sub backend: {backend_type}")
```
**AsyncProcessor'da Kullanı
```python
# In async_processor.py
class AsyncProcessor:
def __init__ (self, **params):
self.id = params.get("id")
# Create backend from config (replaces PulsarClient)
self.pubsub = get_pubsub(**params)
# Rest of initialization...
```
### Arka Uç Arayüzü
```python
class PubSubBackend(Protocol):
"""Protocol defining the interface all pub/sub backends must implement."""
def create_producer(self, topic: str, schema: type, **options) -> BackendProducer:
"""
Create a producer for a topic.
Args:
topic: Generic topic format (qos/tenant/namespace/queue)
schema: Dataclass type for messages
options: Backend-specific options (e.g., chunking_enabled)
Returns:
Backend-specific producer instance
"""
...
def create_consumer(
self,
topic: str,
subscription: str,
schema: type,
initial_position: str = 'latest',
consumer_type: str = 'shared',
**options
) -> BackendConsumer:
"""
Create a consumer for a topic.
Args:
topic: Generic topic format (qos/tenant/namespace/queue)
subscription: Subscription/consumer group name
schema: Dataclass type for messages
initial_position: 'earliest' or 'latest' (MQTT may ignore)
consumer_type: 'shared', 'exclusive', 'failover' (MQTT may ignore)
options: Backend-specific options
Returns:
Backend-specific consumer instance
"""
...
def close(self) -> None:
"""Close the backend connection."""
...
```
```python
class BackendProducer(Protocol):
"""Protocol for backend-specific producer."""
def send(self, message: Any, properties: dict = {}) -> None:
"""Send a message (dataclass instance) with optional properties."""
...
def flush(self) -> None:
"""Flush any buffered messages."""
...
def close(self) -> None:
"""Close the producer."""
...
```
```python
class BackendConsumer(Protocol):
"""Protocol for backend-specific consumer."""
def receive(self, timeout_millis: int = 2000) -> Message:
"""
Receive a message from the topic.
Raises:
TimeoutError: If no message received within timeout
"""
...
def acknowledge(self, message: Message) -> None:
"""Acknowledge successful processing of a message."""
...
def negative_acknowledge(self, message: Message) -> None:
"""Negative acknowledge - triggers redelivery."""
...
def unsubscribe(self) -> None:
"""Unsubscribe from the topic."""
...
def close(self) -> None:
"""Close the consumer."""
...
```
```python
class Message(Protocol):
"""Protocol for a received message."""
def value(self) -> Any:
"""Get the deserialized message (dataclass instance)."""
...
def properties(self) -> dict:
"""Get message properties/metadata."""
...
```
### Mevcut Sı ı ı
Mevcut `Consumer` , `Producer` , `Publisher` , `Subscriber` sı ı ı ı ı
**Mevcut sorumluluklar (saklanacak):**
Asenkron iş parçacı ı ı
Yeniden bağlantı ı ı
Ölçüm toplama
Hı ı ı
Eşzamanlı ı
**Gerekli değişiklikler:**
Doğrudan Pulsar içe aktarmaları ı ı ı `pulsar.schema` , `pulsar.InitialPosition` , vb.)
`BackendProducer` /`BackendConsumer` 'i Pulsar istemcisi yerine kullanı
Gerçek yayı
Genel kavramları ı ı
**Örnek yeniden düzenleme:**
```python
# OLD - consumer.py
class Consumer:
def __init__ (self, client, topic, subscriber, schema, ...):
self.client = client # Direct Pulsar client
# ...
async def consumer_run(self):
# Uses pulsar.InitialPosition, pulsar.ConsumerType
self.consumer = self.client.subscribe(
topic=self.topic,
schema=JsonSchema(self.schema),
initial_position=pulsar.InitialPosition.Earliest,
consumer_type=pulsar.ConsumerType.Shared,
)
# NEW - consumer.py
class Consumer:
def __init__ (self, backend_consumer, schema, ...):
self.backend_consumer = backend_consumer # Backend-specific consumer
self.schema = schema
# ...
async def consumer_run(self):
# Backend consumer already created with right settings
# Just use it directly
while self.running:
msg = await asyncio.to_thread(
self.backend_consumer.receive,
timeout_millis=2000
)
await self.handle_message(msg)
```
### Arka Uç Özel Davranı
**Pulsar Arka Uç:**
`q0` 'ı `non-persistent://` 'e, `q1` /`q2` 'ü `persistent://` 'e eşler.
Tüm tüketici türlerini (paylaşı ı
Başlangı
Yerel mesaj onayı
Şema kayı
**MQTT Arka Uç:**
`q0` /`q1` /`q2` 'yi MQTT QoS seviyeleri 0/1/2'ye eşler.
Adlandı ı ı
Abonelik adları
Başlangı
Tüketici türünü yoksayar (MQTT, tüketici grupları ı
Basit yayı
### Tasarı ı
1. ✅ **Genel kuyruk adlandı ı : `qos/tenant/namespace/queue-name` formatı
2. ✅ **Kuyruk kimliğindeki QoS** : Kuyruk tanı ı ı ı ı
3. ✅ **Yeniden bağlanma** : Tüketici/Üretici sı ı ı ı ı
4. ✅ **MQTT konuları : Doğru adlandı ı ı
5. ✅ **Mesaj geçmişi** : MQTT, `initial_position` parametresini yoksayar (gelecek geliştirmeler).
6. ✅ **İstemci kimlikleri** : MQTT arka ucu, abonelik adı
### Gelecek Geliştirmeler
**MQTT mesaj geçmişi:**
İsteğe bağlı ı ı ı ı
`initial_position='earliest'` 'ı ı ı
Başlangı ı
