streamgate 2.0.0__tar.gz → 2.1.0__tar.gz

{streamgate-2.0.0 → streamgate-2.1.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-09-11
+
+### Added
+
+- **`RedisGroupDedupCache.confirm_empty(group)`** — an explicit "confirmed
+  empty" negative-cache state for group keys. Writes a reserved marker field
+  into the group HASH (`_GROUP_EMPTY_MARKER`, TTL follows
+  `group_ttl_seconds`, idle-GC); afterwards `group_exists()` is `True` and
+  `get_group_fields()` returns `{}`, so enumeration queries stop re-sourcing a
+  known-empty group from the DB on every call. `get_identity_meta` /
+  `get_group_fields` filter the marker; `group_exists` semantics are unchanged
+  ("key present ⇒ group state authoritative, possibly empty"). Purely additive
+  — no existing signature changed.
+- **`RedisGroupDedupCarrier.load_group_refill(group)`** — public primitive
+  exposing the whole-group cold load + backfill path for reuse by enumeration
+  (query) sides instead of copying the mechanism: group-level single-flight,
+  concurrency gate, chunked backfill and the "only a successful whole-group
+  backfill creates the key" invariant are all shared with `admit` stage 3. It
+  returns a `GroupLoadOutcome` (`FOUND` / `EMPTY` / `FAILED` / `GATE_FULL`);
+  policy (endpoints, response bodies, HTTP 429/502, `source` labels) stays in
+  the caller's adapter layer. `GroupLoadOutcome` / `GroupLoadResult` are now
+  exported from `streamgate.contrib.redis_dedup`.
+
 ## [2.0.0] - 2026-09-11
 
 ### BREAKING — unified backfill contract (feat!)

{streamgate-2.0.0 → streamgate-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: streamgate
-Version: 2.0.0
+Version: 2.1.0
 Summary: A pure-core Kafka data pipeline framework: conditional admission, reliable delivery, and one obvious consume-loop outlet via a typed handler.
 Project-URL: Homepage, https://github.com/pwg-code/streamgate
 Project-URL: Repository, https://github.com/pwg-code/streamgate

{streamgate-2.0.0 → streamgate-2.1.0}/src/streamgate/__init__.py

@@ -85,7 +85,7 @@ from streamgate.resilience.health import (
 from streamgate.transport.codec import JsonEnvelopeCodec
 from streamgate.transport.kafka import KafkaConsumerService
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 __all__ = [
     "AllowAllSignal",

{streamgate-2.0.0 → streamgate-2.1.0}/src/streamgate/contrib/redis_dedup/__init__.py

@@ -24,6 +24,8 @@ try:
     from streamgate.contrib.redis_dedup.config import RedisConfig
     from streamgate.contrib.redis_dedup.group_cache import RedisGroupDedupCache
     from streamgate.contrib.redis_dedup.group_carrier import (
+        GroupLoadOutcome,
+        GroupLoadResult,
         RedisGroupDedupCarrier,
         RedisGroupDedupCarrierConfig,
     )
@@ -32,6 +34,8 @@ except ModuleNotFoundError as e:
 
 __all__ = [
     "ColdPathGateFullError",
+    "GroupLoadOutcome",
+    "GroupLoadResult",
     "RedisConfig",
     "RedisDedupCache",
     "RedisDedupCarrier",

{streamgate-2.0.0 → streamgate-2.1.0}/src/streamgate/contrib/redis_dedup/group_cache.py

@@ -6,8 +6,12 @@
 - 幂等摘要写：HSET + EXPIRE 无条件续期（force / on_persisted / 回填共用）
 - 整组回填 write_group_fields：pipeline 分片写入（分片为纯实现细节，无配置、无上界），
   写后统一 EXPIRE
-- 组存在探测 group_exists：EXISTS。组 key 生命周期不可变：仅"整组回填成功"或
-  "空组确认后首身份占位"两条路径创建 → 组 key 存在 ⇒ 组内判定可信，无需空组哨兵
+- 组存在探测 group_exists：EXISTS。组 key 生命周期不可变：仅"整组回填成功"、
+  "空组确认后首身份占位"、"整组确认空标记 confirm_empty"三条路径创建 →
+  组 key 存在 ⇒ 组状态可信（含"已确认空"负缓存态），判定快路径照常成立
+- "确认空组"以专用 field 标记（_GROUP_EMPTY_MARKER）落 HASH：枚举查询侧
+  group_exists=True 直接零 DB，get_group_fields 过滤该标记返回 {}；判重侧
+  phase 2 快路径不变（field 缺失 = 组内确认无此身份）
 - fail-closed 与否是判重载体的参数，缓存层只如实报告错误
 """
 
@@ -29,6 +33,12 @@ _HEALTH_TIMEOUT_S = 2.0
 # 整组回填分片大小（纯实现细节：一次 HSET 的 field 数量上限，非业务配置）
 _WRITE_CHUNK_SIZE = 200
 
+# "整组确认空"负缓存标记：作为独立 field 写入组 HASH，标记该组已获 DB 确认无记录。
+# 组 key 因此存在（group_exists=True），枚举查询侧不再判"冷"反复整组回源；
+# 判定快路径语义不变（field 缺失 = 组内确认无此身份）。取值需保证不可能与
+# 真实组内身份重名。
+_GROUP_EMPTY_MARKER = "__streamgate_group_empty__"
+
 # 原子组内占位（单 key，Cluster 兼容）：命中即返回既有摘要，未命中写入 + TTL
 # KEYS[1]=group key, ARGV=[identity, summary_json, ttl_seconds]
 # 返回 [1, ""] = 占位成功；[0, existing_json] = 已被占（竞态输家未写入，不续期）
@@ -131,7 +141,7 @@ class RedisGroupDedupCache:
                 self._require_client().hget(self.group_key(group), identity),
             )
         )
-        if raw is None:
+        if raw is None or identity == _GROUP_EMPTY_MARKER:
             return None
         return parse_summary(str(raw))
 
@@ -142,7 +152,11 @@ class RedisGroupDedupCache:
                 self._require_client().hgetall(self.group_key(group)),
             )
         )
-        return {identity: parse_summary(str(payload)) for identity, payload in raw.items()}
+        return {
+            identity: parse_summary(str(payload))
+            for identity, payload in raw.items()
+            if identity != _GROUP_EMPTY_MARKER
+        }
 
     async def get_ttl(self, group: str) -> int:
         return int(
@@ -150,6 +164,8 @@ class RedisGroupDedupCache:
         )
 
     async def group_exists(self, group: str) -> bool:
+        """组存在探测。组 key 存在 ⇒ 组状态可信（含"已确认空"负缓存态），
+        判定快路径照常成立：field 缺失 = DB 内确认无此身份。"""
         hits = int(
             await self._read(self._require_client().exists(self.group_key(group)))
         )
@@ -208,6 +224,21 @@ class RedisGroupDedupCache:
             pipe.expire(key, self._config.group_ttl_seconds)
             await self._write(pipe.execute())
 
+    async def confirm_empty(self, group: str) -> None:
+        """标记"整组确认空"负缓存态：写专用 marker + EXPIRE（TTL 沿用
+        group_ttl_seconds，idle GC）。
+
+        此后 group_exists() 为 True（键存在 ⇒ 组状态可信，可能为空）且
+        get_group_fields() 返回 {}，枚举查询侧不再判"冷"反复整组回源。
+        判重 phase 2 快路径不变：组内 field 缺失 = DB 确认无此身份 → 占位。
+        调用前提由使用方保证：仅在 DB 确认组无记录后调用（写库后无自我失效
+        语义）。
+
+        marker 已被 get_identity_meta / get_group_fields 过滤，不会以真实
+        身份或字段泄漏给上层。
+        """
+        await self.write_summary(group, _GROUP_EMPTY_MARKER, {})
+
     async def delete_group(self, group: str) -> None:
         """删除整组（供告警/运维删键修复）。"""
         await self._write(self._require_client().delete(self.group_key(group)))

{streamgate-2.0.0 → streamgate-2.1.0}/src/streamgate/contrib/redis_dedup/group_carrier.py

@@ -4,8 +4,11 @@
 - 组键 = HASH（field = 组内身份），以组为单位缓存，整组一次冷回源预热
 - admit 三阶段：组内缓存判定 → 组存在快路径（零 DB）→ 全新组冷回源
   （组级单飞 + 并发闸门）
-- 组 key 生命周期不可变：仅"整组回填成功"或"空组确认后首身份占位"两条路径
-  创建 → 组 key 存在 ⇒ 组内判定可信（无需任何安全阀/开关）
+- 组 key 生命周期不可变：仅"整组回填成功"、"空组确认后首身份占位"、
+  "整组确认空标记（cache.confirm_empty）"三条路径创建 → 组 key 存在 ⇒
+  组状态可信（可能为空），无需任何安全阀/开关
+- load_group_refill(group) 公开"整组冷回源 + 回填建键"原语：复用组级单飞 +
+  并发闸门 + 分片回填（与 admit 阶段3 同一机制），供枚举查询侧复用避免复制
 
 框架保证调用时序：admit → (Kafka 发送) → on_send_success（每次成功，通知型）/
 on_send_failed（每次失败，默认保留占位 TTL 自愈）→ on_force_accepted（仅
@@ -365,6 +368,31 @@ class RedisGroupDedupCarrier(Generic[RecordModelT]):
             mapping=fields,
         )
 
+    # ---- 公开原语：整组冷回源 + 回填（枚举查询侧复用，避免复制机制）----
+
+    async def load_group_refill(self, group: str) -> GroupLoadOutcome:
+        """整组冷回源 + 回填建键（公开原语，供枚举查询侧复用）。
+
+        与 admit 阶段3 复用同一机制与不变式：
+        - 组级单飞：同组并发首触只回源一次，Future 共享；等待方不悬挂；
+        - 并发闸门：闸门满返回 GATE_FULL 态，不触碰 DB（REJECT 方向）；
+        - 整组分片回填后统一续期；仅整组回填成功才建键（write_group_fields
+          分片写出自动建键），半组/失败不成键、不对外判定。
+
+        返回 GroupLoadOutcome（三态）：
+        - FOUND：组内字段已回填，使用方 get_group_fields(group) 直接命中；
+        - EMPTY：DB 确认组无记录，使用方可选 cache.confirm_empty(group)
+          落"确认空"负缓存，消除后续冷回源；
+        - FAILED / GATE_FULL：不建键，由使用方按策略处置。
+
+        边界：本方法只暴露机制，不纳入枚举查询端点/响应体/HTTP 429-502/
+        source 标签等策略内容（mechanism vs policy）。
+        """
+        outcome = await self._load_group_single_flight(group)
+        if outcome.result is GroupLoadResult.FOUND:
+            await self._backfill_best_effort(group, outcome.mapping)
+        return outcome
+
     # ---- 占位与回填 ----
 
     async def _reserve(
@@ -466,6 +494,7 @@ class RedisGroupDedupCarrier(Generic[RecordModelT]):
 
 
 __all__ = [
+    "GroupLoadOutcome",
     "GroupLoadResult",
     "RedisGroupDedupCarrier",
     "RedisGroupDedupCarrierConfig",