From a3f382cff97bb600f928bda9c842e65a1ebf2996 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 23 May 2026 18:36:12 +0800 Subject: [PATCH 01/24] feat(event): add SubscriptionKey/NormalizeParams/Match fields; change cleanup to func() error Change-Id: I23ba07c089b2c0eb3e42451d8118849a1c5f7a9d --- internal/event/consume/consume.go | 6 ++-- internal/event/types.go | 48 ++++++++++++++++++++++++++++++- 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/internal/event/consume/consume.go b/internal/event/consume/consume.go index 6c862705a..cb39ef6d5 100644 --- a/internal/event/consume/consume.go +++ b/internal/event/consume/consume.go @@ -83,7 +83,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin return fmt.Errorf("handshake failed: %w", err) } - var cleanup func() + var cleanup func() error if ack.FirstForKey && keyDef.PreConsume != nil { if !opts.Quiet { fmt.Fprintf(errOut, "[event] running pre-consume setup...\n") @@ -106,12 +106,12 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin switch { case r != nil: fmt.Fprintf(errOut, "WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n", opts.EventKey) - cleanup() + _ = cleanup() // proper error handling added in Task 9 case lastForKey: if !opts.Quiet { fmt.Fprintf(errOut, "[event] running cleanup...\n") } - cleanup() + _ = cleanup() // proper error handling added in Task 9 if !opts.Quiet { fmt.Fprintf(errOut, "[event] cleanup done.\n") } diff --git a/internal/event/types.go b/internal/event/types.go index 4dde301ae..cdc86f14b 100644 --- a/internal/event/types.go +++ b/internal/event/types.go @@ -55,6 +55,16 @@ type ParamDef struct { Default string `json:"default,omitempty"` Description string `json:"description"` Values []ParamValue `json:"values,omitempty"` + + // SubscriptionKey marks this param as part of the subscription identity. + // Two consumers of the same EventKey but different values for any + // SubscriptionKey-marked param are treated as DISTINCT subscriptions: + // PreConsume runs once per (EventKey, SubscriptionID), cleanup runs once per + // (EventKey, SubscriptionID). + // + // Default false = the param is a filter / formatting / metadata param + // and does not affect subscription identity. + SubscriptionKey bool `json:"subscription_key,omitempty"` } type ProcessFunc = func(ctx context.Context, rt APIClient, raw *RawEvent, params map[string]string) (json.RawMessage, error) @@ -83,10 +93,46 @@ type KeyDefinition struct { Schema SchemaDef `json:"schema"` + // NormalizeParams canonicalizes param values BEFORE fingerprint compute, + // PreConsume, Match, and Process. Mutates the params map in place. + // May call OAPI; runs once per consumer at startup. + // + // Use cases: resolve aliases like mail "me" -> real email, name -> ID + // lookups, trim whitespace. On error, consume fails (no retry); caller + // gets the wrapped error. + // + // Default nil = no normalization, params pass through unchanged. + NormalizeParams func(ctx context.Context, rt APIClient, params map[string]string) error `json:"-"` + // Process required when Schema.Custom is Processed output; must be nil when Native is used. + // + // Convention: returning (nil, nil) signals "drop this event" — the + // consumer loop will skip writing it to sink and not advance the + // emitted counter. Useful for async filtering (e.g. fetch metadata, + // drop if folder doesn't match). For sync filters that don't need + // OAPI, use Match instead. Process func(ctx context.Context, rt APIClient, raw *RawEvent, params map[string]string) (json.RawMessage, error) `json:"-"` - PreConsume func(ctx context.Context, rt APIClient, params map[string]string) (cleanup func(), err error) `json:"-"` + // Match is a synchronous payload filter run on every received event + // BEFORE Process. Return false to drop the event without further work. + // + // Signature deliberately omits ctx/rt to physically enforce "no OAPI + // calls in Match". For filters that need metadata fetch (e.g. mail + // folders/labels resolution), use Process and return nil to drop. + // + // Default nil = accept all events. + Match func(raw *RawEvent, params map[string]string) bool `json:"-"` + + // PreConsume runs once per (EventKey, SubscriptionID) when this consumer + // is first for that scope. Returns a cleanup function that the framework + // invokes when this consumer is the last for its scope. + // + // cleanup signature: func() error. + // - The error return is honored by the framework: on nil, stderr prints + // "[event] cleanup done."; on non-nil, stderr prints WARN with an + // idempotency note. (Branching wired in Task 9; pre-Task-9 stub + // ignores the error.) + PreConsume func(ctx context.Context, rt APIClient, params map[string]string) (cleanup func() error, err error) `json:"-"` Scopes []string `json:"scopes,omitempty"` From 790d621f862ea08f35d0e69e3cb7bf9249ae299f Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 23 May 2026 18:43:51 +0800 Subject: [PATCH 02/24] feat(event): add ComputeSubscriptionID for per-resource subscription dedup Change-Id: Iaeb09c15c754c9e4ca8ce9784623f82f55fe308b --- internal/event/consume/fingerprint.go | 54 +++++++++ internal/event/consume/fingerprint_test.go | 127 +++++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 internal/event/consume/fingerprint.go create mode 100644 internal/event/consume/fingerprint_test.go diff --git a/internal/event/consume/fingerprint.go b/internal/event/consume/fingerprint.go new file mode 100644 index 000000000..688452fc6 --- /dev/null +++ b/internal/event/consume/fingerprint.go @@ -0,0 +1,54 @@ +// internal/event/consume/fingerprint.go +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package consume + +import ( + "crypto/sha256" + "encoding/base64" + "encoding/json" + "sort" + + "github.com/larksuite/cli/internal/event" +) + +// ComputeSubscriptionID returns a stable identifier scoped to (EventKey, values +// of all ParamDef entries with SubscriptionKey=true). Used by the framework +// to dedup PreConsume/cleanup gates and route Hub keyCounts per-subscription. +// +// Algorithm: +// 1. Collect [name, value] pairs for every ParamDef with SubscriptionKey=true. +// Values come from the params map; missing keys are treated as empty string. +// 2. Sort the pairs by Name to make the result order-independent of ParamDef +// declaration order. +// 3. Canonical JSON-encode the sorted list. +// 4. sha256, truncate to 12 bytes (96 bits), base64URL without padding (16 chars). +// 5. Return ":<16-char fingerprint>". +// +// Degenerate case: no params are SubscriptionKey -> return def.Key verbatim +// (matches today's one-dimensional behavior; backward-compatible with legacy daemons). +// +// Stability contract: same EventKey + same param values (after caller-side +// normalization) -> same SubscriptionID across CLI versions. Changing this +// algorithm requires a wire-format version bump. +func ComputeSubscriptionID(def *event.KeyDefinition, params map[string]string) string { + type kv struct { + Name string `json:"name"` + Value string `json:"value"` + } + var subParams []kv + for _, p := range def.Params { + if !p.SubscriptionKey { + continue + } + subParams = append(subParams, kv{Name: p.Name, Value: params[p.Name]}) + } + if len(subParams) == 0 { + return def.Key + } + sort.Slice(subParams, func(i, j int) bool { return subParams[i].Name < subParams[j].Name }) + raw, _ := json.Marshal(subParams) // err impossible: kv has no unmarshalable fields + sum := sha256.Sum256(raw) + return def.Key + ":" + base64.RawURLEncoding.EncodeToString(sum[:12]) +} diff --git a/internal/event/consume/fingerprint_test.go b/internal/event/consume/fingerprint_test.go new file mode 100644 index 000000000..2eaacc4f3 --- /dev/null +++ b/internal/event/consume/fingerprint_test.go @@ -0,0 +1,127 @@ +// internal/event/consume/fingerprint_test.go +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package consume + +import ( + "strings" + "testing" + + "github.com/larksuite/cli/internal/event" +) + +func TestComputeSubscriptionID(t *testing.T) { + makeDef := func(subKeyNames ...string) *event.KeyDefinition { + def := &event.KeyDefinition{Key: "test.evt"} + marked := make(map[string]bool, len(subKeyNames)) + for _, n := range subKeyNames { + marked[n] = true + } + for _, n := range []string{"alpha", "beta", "gamma"} { + def.Params = append(def.Params, event.ParamDef{Name: n, SubscriptionKey: marked[n]}) + } + return def + } + + t.Run("no SubscriptionKey params returns EventKey verbatim", func(t *testing.T) { + def := makeDef() + got := ComputeSubscriptionID(def, map[string]string{"alpha": "x", "beta": "y"}) + if got != "test.evt" { + t.Errorf("got %q, want %q", got, "test.evt") + } + }) + + t.Run("single SubscriptionKey param: non-sub params do not leak into ID", func(t *testing.T) { + def := makeDef("alpha") + id1 := ComputeSubscriptionID(def, map[string]string{"alpha": "value1", "beta": "ignored"}) + id2 := ComputeSubscriptionID(def, map[string]string{"alpha": "value1", "beta": "different"}) + if id1 != id2 { + t.Errorf("non-SubscriptionKey param change leaked into ID: %q vs %q", id1, id2) + } + }) + + t.Run("different SubscriptionKey value produces different ID", func(t *testing.T) { + def := makeDef("alpha") + id1 := ComputeSubscriptionID(def, map[string]string{"alpha": "v1"}) + id2 := ComputeSubscriptionID(def, map[string]string{"alpha": "v2"}) + if id1 == id2 { + t.Errorf("different values produced same ID: %q", id1) + } + }) +} + +func TestComputeSubscriptionID_Stability(t *testing.T) { + // Param order in the ParamDef list must not affect the result (sorted by name internally). + def1 := &event.KeyDefinition{ + Key: "test.evt", + Params: []event.ParamDef{ + {Name: "b", SubscriptionKey: true}, + {Name: "a", SubscriptionKey: true}, + }, + } + def2 := &event.KeyDefinition{ + Key: "test.evt", + Params: []event.ParamDef{ + {Name: "a", SubscriptionKey: true}, + {Name: "b", SubscriptionKey: true}, + }, + } + id1 := ComputeSubscriptionID(def1, map[string]string{"a": "1", "b": "2"}) + id2 := ComputeSubscriptionID(def2, map[string]string{"a": "1", "b": "2"}) + if id1 != id2 { + t.Errorf("order-sensitive: id1=%q id2=%q", id1, id2) + } +} + +func TestComputeSubscriptionID_Format(t *testing.T) { + def := &event.KeyDefinition{ + Key: "mail.user_mailbox.event.message_received_v1", + Params: []event.ParamDef{{Name: "mailbox", SubscriptionKey: true}}, + } + id := ComputeSubscriptionID(def, map[string]string{"mailbox": "liuxinyang@example.com"}) + prefix := "mail.user_mailbox.event.message_received_v1:" + if !strings.HasPrefix(id, prefix) { + t.Fatalf("missing prefix: %q", id) + } + suffix := strings.TrimPrefix(id, prefix) + if len(suffix) != 16 { + t.Errorf("fingerprint length = %d, want 16", len(suffix)) + } + for _, c := range suffix { + isValid := (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '_' + if !isValid { + t.Errorf("non-base64URL char in fingerprint: %q", suffix) + break + } + } +} + +func TestComputeSubscriptionID_UnicodeAndSpecialChars(t *testing.T) { + def := &event.KeyDefinition{ + Key: "test.evt", + Params: []event.ParamDef{{Name: "value", SubscriptionKey: true}}, + } + for _, val := range []string{"中文", "emoji🚀", "with spaces", "with:colons", "with\"quotes"} { + id := ComputeSubscriptionID(def, map[string]string{"value": val}) + if !strings.HasPrefix(id, "test.evt:") || len(id) != len("test.evt:")+16 { + t.Errorf("ID malformed for value=%q: %q (len=%d)", val, id, len(id)) + } + } +} + +func TestComputeSubscriptionID_EmptyValue(t *testing.T) { + def := &event.KeyDefinition{ + Key: "test.evt", + Params: []event.ParamDef{{Name: "x", SubscriptionKey: true}}, + } + id1 := ComputeSubscriptionID(def, map[string]string{"x": ""}) + id2 := ComputeSubscriptionID(def, map[string]string{}) // missing entirely + if id1 != id2 { + t.Errorf("empty value should be indistinguishable from missing: %q vs %q", id1, id2) + } + id3 := ComputeSubscriptionID(def, map[string]string{"x": "nonempty"}) + if id1 == id3 { + t.Errorf("empty and nonempty produced same ID: %q", id1) + } +} From 66a7f1dd16db964b761a53b96d3ed9d60a564f78 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 23 May 2026 18:54:03 +0800 Subject: [PATCH 03/24] feat(event/protocol): add SubscriptionID to Hello/PreShutdownCheck/ConsumerInfo Add SubscriptionID field (omitempty) to Hello, PreShutdownCheck, and ConsumerInfo. Update NewHello and NewPreShutdownCheck constructors to accept subscriptionID param; patch all call sites with "" placeholder pending Tasks 7/8. Change-Id: I469a1fb0de2c31326513feef5693d8097dfc8415 --- internal/event/consume/handshake.go | 2 +- internal/event/consume/shutdown.go | 2 +- internal/event/protocol/codec_test.go | 85 ++++++++++++++++++++++++ internal/event/protocol/messages.go | 44 ++++++------ internal/event/protocol/messages_test.go | 6 +- 5 files changed, 114 insertions(+), 25 deletions(-) diff --git a/internal/event/consume/handshake.go b/internal/event/consume/handshake.go index 7aac408de..5994d8e38 100644 --- a/internal/event/consume/handshake.go +++ b/internal/event/consume/handshake.go @@ -19,7 +19,7 @@ const helloAckTimeout = 5 * time.Second // symmetric with bus-side hello read de // doHello returns a bufio.Reader holding any bytes already pulled off conn so events // buffered with the ack in one TCP segment aren't dropped. func doHello(conn net.Conn, eventKey string, eventTypes []string) (*protocol.HelloAck, *bufio.Reader, error) { - hello := protocol.NewHello(os.Getpid(), eventKey, eventTypes, "v1") + hello := protocol.NewHello(os.Getpid(), eventKey, eventTypes, "v1", "") if err := protocol.EncodeWithDeadline(conn, hello, protocol.WriteTimeout); err != nil { return nil, nil, err } diff --git a/internal/event/consume/shutdown.go b/internal/event/consume/shutdown.go index e41209e2c..b54abf2b0 100644 --- a/internal/event/consume/shutdown.go +++ b/internal/event/consume/shutdown.go @@ -17,7 +17,7 @@ const preShutdownAckTimeout = 2 * time.Second // checkLastForKey atomically reserves a cleanup lock; on any error defaults to true // (cleanup-on-error is safer than leaking server state). Discards non-ack frames in flight. func checkLastForKey(conn net.Conn, eventKey string) bool { - msg := protocol.NewPreShutdownCheck(eventKey) + msg := protocol.NewPreShutdownCheck(eventKey, "") if err := protocol.EncodeWithDeadline(conn, msg, protocol.WriteTimeout); err != nil { return true } diff --git a/internal/event/protocol/codec_test.go b/internal/event/protocol/codec_test.go index 91dbe01f6..979c487a9 100644 --- a/internal/event/protocol/codec_test.go +++ b/internal/event/protocol/codec_test.go @@ -77,3 +77,88 @@ func TestDecodeUnknownType(t *testing.T) { t.Error("expected error for unknown type") } } + +func TestEncodeDecodeHello_WithSubscriptionID(t *testing.T) { + msg := &Hello{ + Type: MsgTypeHello, + PID: 12345, + EventKey: "mail.user_mailbox.event.message_received_v1", + EventTypes: []string{"mail.user_mailbox.event.message_received_v1"}, + Version: "v1", + SubscriptionID: "mail.user_mailbox.event.message_received_v1:a7Bx9Kp2Lm3Qv4Rs", + } + buf := &bytes.Buffer{} + if err := Encode(buf, msg); err != nil { + t.Fatal(err) + } + line := buf.Bytes() + if !bytes.Contains(line, []byte(`"subscription_id":"mail.user_mailbox.event.message_received_v1:a7Bx9Kp2Lm3Qv4Rs"`)) { + t.Errorf("subscription_id not serialized: %s", string(line)) + } + decoded, err := Decode(bytes.TrimRight(line, "\n")) + if err != nil { + t.Fatal(err) + } + hello, ok := decoded.(*Hello) + if !ok { + t.Fatalf("expected *Hello, got %T", decoded) + } + if hello.SubscriptionID != msg.SubscriptionID { + t.Errorf("roundtrip subscription_id: got %q want %q", hello.SubscriptionID, msg.SubscriptionID) + } +} + +func TestEncodeDecodeHello_EmptySubscriptionIDOmitted(t *testing.T) { + msg := &Hello{ + Type: MsgTypeHello, + PID: 1, + EventKey: "k", + EventTypes: []string{"k"}, + Version: "v1", + } + buf := &bytes.Buffer{} + if err := Encode(buf, msg); err != nil { + t.Fatal(err) + } + if bytes.Contains(buf.Bytes(), []byte("subscription_id")) { + t.Errorf("empty subscription_id should be omitted: %s", buf.String()) + } + decoded, _ := Decode(bytes.TrimRight(buf.Bytes(), "\n")) + hello := decoded.(*Hello) + if hello.SubscriptionID != "" { + t.Errorf("got %q, want empty", hello.SubscriptionID) + } +} + +func TestEncodeDecodePreShutdownCheck_WithSubscriptionID(t *testing.T) { + msg := &PreShutdownCheck{ + Type: MsgTypePreShutdownCheck, + EventKey: "mail.x", + SubscriptionID: "mail.x:abc", + } + buf := &bytes.Buffer{} + if err := Encode(buf, msg); err != nil { + t.Fatal(err) + } + decoded, err := Decode(bytes.TrimRight(buf.Bytes(), "\n")) + if err != nil { + t.Fatal(err) + } + got := decoded.(*PreShutdownCheck) + if got.SubscriptionID != msg.SubscriptionID { + t.Errorf("roundtrip: got %q want %q", got.SubscriptionID, msg.SubscriptionID) + } +} + +func TestStatusResponse_ConsumerInfo_SubscriptionID(t *testing.T) { + msg := NewStatusResponse(7, 120, 1, []ConsumerInfo{ + {PID: 99, EventKey: "mail.x", SubscriptionID: "mail.x:abc", Received: 5, Dropped: 0}, + }) + buf := &bytes.Buffer{} + if err := Encode(buf, msg); err != nil { + t.Fatal(err) + } + if !bytes.Contains(buf.Bytes(), []byte(`"subscription_id":"mail.x:abc"`)) { + t.Errorf("ConsumerInfo.SubscriptionID missing from JSON: %s", buf.String()) + } +} diff --git a/internal/event/protocol/messages.go b/internal/event/protocol/messages.go index 0effa36c0..9274c6476 100644 --- a/internal/event/protocol/messages.go +++ b/internal/event/protocol/messages.go @@ -34,11 +34,12 @@ type SourceStatus struct { } type Hello struct { - Type string `json:"type"` - PID int `json:"pid"` - EventKey string `json:"event_key"` - EventTypes []string `json:"event_types"` - Version string `json:"version"` + Type string `json:"type"` + PID int `json:"pid"` + EventKey string `json:"event_key"` + EventTypes []string `json:"event_types"` + Version string `json:"version"` + SubscriptionID string `json:"subscription_id,omitempty"` // empty = fallback to EventKey on bus side } type HelloAck struct { @@ -61,10 +62,11 @@ type Bye struct { Type string `json:"type"` } -// PreShutdownCheck atomically reserves the cleanup lock for EventKey. +// PreShutdownCheck atomically reserves the cleanup lock for (EventKey, SubscriptionID). type PreShutdownCheck struct { - Type string `json:"type"` - EventKey string `json:"event_key"` + Type string `json:"type"` + EventKey string `json:"event_key"` + SubscriptionID string `json:"subscription_id,omitempty"` // empty = fallback to EventKey } type PreShutdownAck struct { @@ -77,10 +79,11 @@ type StatusQuery struct { } type ConsumerInfo struct { - PID int `json:"pid"` - EventKey string `json:"event_key"` - Received int64 `json:"received"` - Dropped int64 `json:"dropped"` + PID int `json:"pid"` + EventKey string `json:"event_key"` + SubscriptionID string `json:"subscription_id,omitempty"` + Received int64 `json:"received"` + Dropped int64 `json:"dropped"` } type StatusResponse struct { @@ -95,13 +98,14 @@ type Shutdown struct { Type string `json:"type"` } -func NewHello(pid int, eventKey string, eventTypes []string, version string) *Hello { +func NewHello(pid int, eventKey string, eventTypes []string, version string, subscriptionID string) *Hello { return &Hello{ - Type: MsgTypeHello, - PID: pid, - EventKey: eventKey, - EventTypes: eventTypes, - Version: version, + Type: MsgTypeHello, + PID: pid, + EventKey: eventKey, + EventTypes: eventTypes, + Version: version, + SubscriptionID: subscriptionID, } } @@ -124,8 +128,8 @@ func NewEvent(eventType, eventID, sourceTime string, seq uint64, payload json.Ra } } -func NewPreShutdownCheck(eventKey string) *PreShutdownCheck { - return &PreShutdownCheck{Type: MsgTypePreShutdownCheck, EventKey: eventKey} +func NewPreShutdownCheck(eventKey, subscriptionID string) *PreShutdownCheck { + return &PreShutdownCheck{Type: MsgTypePreShutdownCheck, EventKey: eventKey, SubscriptionID: subscriptionID} } func NewPreShutdownAck(lastForKey bool) *PreShutdownAck { diff --git a/internal/event/protocol/messages_test.go b/internal/event/protocol/messages_test.go index c6ca2bd95..2893789fa 100644 --- a/internal/event/protocol/messages_test.go +++ b/internal/event/protocol/messages_test.go @@ -17,7 +17,7 @@ import ( // Every NewXxx helper must set the Type discriminator (Decode rejects messages without it). func TestConstructors_PinTypeField(t *testing.T) { - if got := NewHello(1, "k", []string{"t"}, "v1"); got.Type != MsgTypeHello { + if got := NewHello(1, "k", []string{"t"}, "v1", ""); got.Type != MsgTypeHello { t.Errorf("NewHello.Type = %q, want %q", got.Type, MsgTypeHello) } if got := NewHelloAck("v1", true); got.Type != MsgTypeHelloAck || !got.FirstForKey { @@ -26,7 +26,7 @@ func TestConstructors_PinTypeField(t *testing.T) { if got := NewEvent("im.msg", "e1", "", 7, json.RawMessage(`{}`)); got.Type != MsgTypeEvent || got.Seq != 7 { t.Errorf("NewEvent mismatch: %+v", got) } - if got := NewPreShutdownCheck("k"); got.Type != MsgTypePreShutdownCheck || got.EventKey != "k" { + if got := NewPreShutdownCheck("k", ""); got.Type != MsgTypePreShutdownCheck || got.EventKey != "k" { t.Errorf("NewPreShutdownCheck mismatch: %+v", got) } if got := NewPreShutdownAck(true); got.Type != MsgTypePreShutdownAck || !got.LastForKey { @@ -63,7 +63,7 @@ func TestEncode_DecodeRoundtripAllTypes(t *testing.T) { } } roundtrip(t, NewHelloAck("v1", true), &HelloAck{}) - roundtrip(t, NewPreShutdownCheck("im.msg"), &PreShutdownCheck{}) + roundtrip(t, NewPreShutdownCheck("im.msg", ""), &PreShutdownCheck{}) roundtrip(t, NewPreShutdownAck(false), &PreShutdownAck{}) roundtrip(t, NewStatusQuery(), &StatusQuery{}) roundtrip(t, NewStatusResponse(7, 120, 1, []ConsumerInfo{{PID: 99, EventKey: "k"}}), &StatusResponse{}) From 4da3e2b05b0399858689e72239887ffb2b81aa64 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 23 May 2026 18:58:45 +0800 Subject: [PATCH 04/24] feat(event/bus): store SubscriptionID on Conn with EventKey fallback Add subID field to Conn, update NewConn signature to accept it, add SubscriptionID() getter (falls back to EventKey when empty), update handleControlMessage PreShutdownCheck branch to use message SubscriptionID with EventKey fallback, and wire hello.SubscriptionID through handleHello. Change-Id: Iea9195dd2d343fd51c84317e4d7f2d5d8067d51d --- internal/event/bus/bus.go | 6 ++++- internal/event/bus/bus_shutdown_test.go | 2 +- internal/event/bus/conn.go | 19 +++++++++++-- internal/event/bus/conn_test.go | 28 +++++++++++++++++--- internal/event/bus/hub_observability_test.go | 10 +++---- 5 files changed, 52 insertions(+), 13 deletions(-) diff --git a/internal/event/bus/bus.go b/internal/event/bus/bus.go index 469e9f12d..4ab33e3cd 100644 --- a/internal/event/bus/bus.go +++ b/internal/event/bus/bus.go @@ -262,7 +262,11 @@ func (b *Bus) handleConn(conn net.Conn) { // handleHello registers a consume connection with the hub; reader carries bytes already pulled off conn. func (b *Bus) handleHello(conn net.Conn, reader *bufio.Reader, hello *protocol.Hello) { - bc := NewConn(conn, reader, hello.EventKey, hello.EventTypes, hello.PID) + subID := hello.SubscriptionID + if subID == "" { + subID = hello.EventKey + } + bc := NewConn(conn, reader, hello.EventKey, hello.EventTypes, hello.PID, subID) bc.SetLogger(b.logger) // Register + isFirst under one lock; blocks on any in-progress cleanup lock for the same EventKey. diff --git a/internal/event/bus/bus_shutdown_test.go b/internal/event/bus/bus_shutdown_test.go index 989caefca..98ff07401 100644 --- a/internal/event/bus/bus_shutdown_test.go +++ b/internal/event/bus/bus_shutdown_test.go @@ -33,7 +33,7 @@ func TestRunShutdownWithMultipleConns(t *testing.T) { server, client := net.Pipe() pipes = append(pipes, server, client) - bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 1000+i) + bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 1000+i, "") bc.SetLogger(logger) hub.RegisterAndIsFirst(bc) diff --git a/internal/event/bus/conn.go b/internal/event/bus/conn.go index 833231ff2..76b2c5d2b 100644 --- a/internal/event/bus/conn.go +++ b/internal/event/bus/conn.go @@ -29,6 +29,7 @@ type Conn struct { writeMu sync.Mutex // serialises all net.Conn writes (Encode+SetWriteDeadline is a 2-call sequence) eventKey string eventTypes []string + subID string pid int onClose func(*Conn) checkLastForKey func(eventKey string) bool @@ -41,7 +42,7 @@ type Conn struct { } // NewConn creates a Conn; pass a reader with pre-buffered bytes (handoff from Bus.handleConn) or nil for a fresh one. -func NewConn(conn net.Conn, reader *bufio.Reader, eventKey string, eventTypes []string, pid int) *Conn { +func NewConn(conn net.Conn, reader *bufio.Reader, eventKey string, eventTypes []string, pid int, subID string) *Conn { if reader == nil { reader = bufio.NewReader(conn) } @@ -52,10 +53,20 @@ func NewConn(conn net.Conn, reader *bufio.Reader, eventKey string, eventTypes [] eventKey: eventKey, eventTypes: eventTypes, pid: pid, + subID: subID, closed: make(chan struct{}), } } +// SubscriptionID returns the subscription identity. Falls back to EventKey +// when the stored subID is empty (legacy clients / no-SubscriptionKey EventKeys). +func (c *Conn) SubscriptionID() string { + if c.subID == "" { + return c.eventKey + } + return c.subID +} + func (c *Conn) SetOnClose(fn func(*Conn)) { c.onClose = fn } // SetCheckLastForKey: returning true means "you are the last subscriber, run cleanup". @@ -136,9 +147,13 @@ func (c *Conn) handleControlMessage(msg interface{}) { case *protocol.Bye: c.shutdown() case *protocol.PreShutdownCheck: + scope := m.SubscriptionID + if scope == "" { + scope = m.EventKey + } lastForKey := true if c.checkLastForKey != nil { - lastForKey = c.checkLastForKey(m.EventKey) + lastForKey = c.checkLastForKey(scope) } ack := protocol.NewPreShutdownAck(lastForKey) if err := c.writeFrame(ack); err != nil && c.logger != nil { diff --git a/internal/event/bus/conn_test.go b/internal/event/bus/conn_test.go index aaa2d4f9d..1beaf3489 100644 --- a/internal/event/bus/conn_test.go +++ b/internal/event/bus/conn_test.go @@ -21,7 +21,7 @@ func TestConn_SenderWritesEvents(t *testing.T) { defer server.Close() defer client.Close() - bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 12345) + bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 12345, "") go bc.SenderLoop() bc.SendCh() <- &protocol.Event{ @@ -62,7 +62,7 @@ func TestConn_ConcurrentWritesSerialised(t *testing.T) { defer client.Close() det := &serializingDetector{Conn: server} - bc := NewConn(det, nil, "im.msg", []string{"im.msg"}, 12345) + bc := NewConn(det, nil, "im.msg", []string{"im.msg"}, 12345, "") go func() { _, _ = io.Copy(io.Discard, client) }() @@ -106,7 +106,7 @@ func TestConn_TrySend_NonEvicting(t *testing.T) { server, client := net.Pipe() defer server.Close() defer client.Close() - bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345) + bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345, "") for i := 0; i < sendChCap; i++ { if !bc.TrySend(i) { @@ -126,7 +126,7 @@ func TestConn_ReaderDetectsEOF(t *testing.T) { server, client := net.Pipe() defer server.Close() - bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345) + bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345, "") done := make(chan struct{}) go func() { @@ -142,3 +142,23 @@ func TestConn_ReaderDetectsEOF(t *testing.T) { t.Fatal("ReaderLoop did not exit on EOF") } } + +func TestConn_SubscriptionID(t *testing.T) { + c1, c2 := net.Pipe() + defer c1.Close() + defer c2.Close() + conn := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 999, "mail.x:abc") + if got := conn.SubscriptionID(); got != "mail.x:abc" { + t.Errorf("SubscriptionID() = %q, want %q", got, "mail.x:abc") + } +} + +func TestConn_SubscriptionID_EmptyFallsBackToEventKey(t *testing.T) { + c1, c2 := net.Pipe() + defer c1.Close() + defer c2.Close() + conn := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 999, "") + if got := conn.SubscriptionID(); got != "mail.x" { + t.Errorf("SubscriptionID() with empty input = %q, want fallback %q", got, "mail.x") + } +} diff --git a/internal/event/bus/hub_observability_test.go b/internal/event/bus/hub_observability_test.go index 051e3501f..0134fe2a5 100644 --- a/internal/event/bus/hub_observability_test.go +++ b/internal/event/bus/hub_observability_test.go @@ -17,7 +17,7 @@ func TestHubDroppedCountIncrements(t *testing.T) { server, client := testNetPipe(t) defer server.Close() defer client.Close() - c := NewConn(server, nil, "k", []string{"t"}, 1) + c := NewConn(server, nil, "k", []string{"t"}, 1, "") c.sendCh = make(chan interface{}, 1) h.RegisterAndIsFirst(c) @@ -35,7 +35,7 @@ func TestPublishAssignsIncrementalSeq(t *testing.T) { server, client := testNetPipe(t) defer server.Close() defer client.Close() - c := NewConn(server, nil, "k", []string{"t"}, 1) + c := NewConn(server, nil, "k", []string{"t"}, 1, "") c.sendCh = make(chan interface{}, 10) h.RegisterAndIsFirst(c) @@ -60,7 +60,7 @@ func TestPublishPopulatesEventIDAndSourceTime(t *testing.T) { server, client := testNetPipe(t) defer server.Close() defer client.Close() - c := NewConn(server, nil, "k", []string{"t"}, 1) + c := NewConn(server, nil, "k", []string{"t"}, 1, "") c.sendCh = make(chan interface{}, 1) h.RegisterAndIsFirst(c) @@ -87,7 +87,7 @@ func TestPublishSourceTimeTakesPrecedence(t *testing.T) { server, client := testNetPipe(t) defer server.Close() defer client.Close() - c := NewConn(server, nil, "k", []string{"t"}, 1) + c := NewConn(server, nil, "k", []string{"t"}, 1, "") c.sendCh = make(chan interface{}, 1) h.RegisterAndIsFirst(c) @@ -111,7 +111,7 @@ func TestPublishSourceTimeFallback(t *testing.T) { server, client := testNetPipe(t) defer server.Close() defer client.Close() - c := NewConn(server, nil, "k", []string{"t"}, 1) + c := NewConn(server, nil, "k", []string{"t"}, 1, "") c.sendCh = make(chan interface{}, 1) h.RegisterAndIsFirst(c) From 7dcd0ceea1c2ca19080e15fe15e87898dba3243a Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 23 May 2026 19:07:02 +0800 Subject: [PATCH 05/24] feat(event/bus): key Hub dedup by SubscriptionID; add SubCount accessor Change-Id: I3cc81e8440656470f92f1b50074b840b0875c781 --- internal/event/bus/bus.go | 2 +- internal/event/bus/hub.go | 77 ++++++++++++------- internal/event/bus/hub_publish_race_test.go | 2 + internal/event/bus/hub_test.go | 84 ++++++++++++++++++++- 4 files changed, 135 insertions(+), 30 deletions(-) diff --git a/internal/event/bus/bus.go b/internal/event/bus/bus.go index 4ab33e3cd..f9bd4e68a 100644 --- a/internal/event/bus/bus.go +++ b/internal/event/bus/bus.go @@ -278,7 +278,7 @@ func (b *Bus) handleHello(conn net.Conn, reader *bufio.Reader, hello *protocol.H bc.SetOnClose(func(c *Conn) { b.hub.UnregisterAndIsLast(c) // Release is idempotent and must fire on every disconnect path so waiters don't block forever. - b.hub.ReleaseCleanupLock(c.EventKey()) + b.hub.ReleaseCleanupLock(c.SubscriptionID()) b.mu.Lock() delete(b.conns, c) remaining := len(b.conns) diff --git a/internal/event/bus/hub.go b/internal/event/bus/hub.go index 76b7d22e1..620d3df64 100644 --- a/internal/event/bus/hub.go +++ b/internal/event/bus/hub.go @@ -16,6 +16,9 @@ import ( // Subscriber is the interface a connection must satisfy for Hub registration. type Subscriber interface { EventKey() string + // SubscriptionID identifies the per-resource subscription for dedup purposes. + // When no resource qualifier is needed it equals EventKey. + SubscriptionID() string EventTypes() []string SendCh() chan interface{} PID() int @@ -34,8 +37,11 @@ type Subscriber interface { type Hub struct { mu sync.RWMutex subscribers map[Subscriber]struct{} - keyCounts map[string]int - // cleanupInProgress[key] holds a channel closed on release; presence means a cleanup lock is held. + // subCounts is keyed by SubscriptionID (not EventKey) so that different + // per-resource subscriptions sharing the same EventKey are deduped independently. + subCounts map[string]int + // cleanupInProgress[subscriptionID] holds a channel closed on release; + // presence means a cleanup lock is held for that subscription. cleanupInProgress map[string]chan struct{} logger atomic.Pointer[log.Logger] } @@ -43,7 +49,7 @@ type Hub struct { func NewHub() *Hub { return &Hub{ subscribers: make(map[Subscriber]struct{}), - keyCounts: make(map[string]int), + subCounts: make(map[string]int), cleanupInProgress: make(map[string]chan struct{}), } } @@ -51,7 +57,7 @@ func NewHub() *Hub { // SetLogger attaches a logger (nil tolerated). func (h *Hub) SetLogger(l *log.Logger) { h.logger.Store(l) } -// UnregisterAndIsLast removes s and reports whether it was last for its EventKey; stale unregisters are no-ops. +// UnregisterAndIsLast removes s and reports whether it was last for its SubscriptionID; stale unregisters are no-ops. func (h *Hub) UnregisterAndIsLast(s Subscriber) bool { h.mu.Lock() defer h.mu.Unlock() @@ -59,34 +65,35 @@ func (h *Hub) UnregisterAndIsLast(s Subscriber) bool { return false } delete(h.subscribers, s) - h.keyCounts[s.EventKey()]-- - isLast := h.keyCounts[s.EventKey()] == 0 + sid := s.SubscriptionID() + h.subCounts[sid]-- + isLast := h.subCounts[sid] == 0 if isLast { - delete(h.keyCounts, s.EventKey()) + delete(h.subCounts, sid) } return isLast } -// AcquireCleanupLock reserves cleanup rights iff exactly one subscriber exists for eventKey and no lock is held. +// AcquireCleanupLock reserves cleanup rights iff exactly one subscriber exists for subscriptionID and no lock is held. // Count==0 is rejected (would block future Register calls). On true return, caller MUST Release. -func (h *Hub) AcquireCleanupLock(eventKey string) bool { +func (h *Hub) AcquireCleanupLock(subscriptionID string) bool { h.mu.Lock() defer h.mu.Unlock() - if h.keyCounts[eventKey] != 1 { + if h.subCounts[subscriptionID] != 1 { return false } - if _, alreadyLocked := h.cleanupInProgress[eventKey]; alreadyLocked { + if _, alreadyLocked := h.cleanupInProgress[subscriptionID]; alreadyLocked { return false } - h.cleanupInProgress[eventKey] = make(chan struct{}) + h.cleanupInProgress[subscriptionID] = make(chan struct{}) return true } // ReleaseCleanupLock is idempotent; OnClose calls unconditionally. -func (h *Hub) ReleaseCleanupLock(eventKey string) { +func (h *Hub) ReleaseCleanupLock(subscriptionID string) { h.mu.Lock() - ch := h.cleanupInProgress[eventKey] - delete(h.cleanupInProgress, eventKey) + ch := h.cleanupInProgress[subscriptionID] + delete(h.cleanupInProgress, subscriptionID) h.mu.Unlock() if ch != nil { close(ch) @@ -94,23 +101,24 @@ func (h *Hub) ReleaseCleanupLock(eventKey string) { } // RegisterAndIsFirst adds s to the hub and reports whether it's the first -// subscriber for its EventKey. If a cleanup is in progress for -// s.EventKey() (another conn holds the cleanup lock), this waits until +// subscriber for its SubscriptionID. If a cleanup is in progress for +// s.SubscriptionID() (another conn holds the cleanup lock), this waits until // cleanup releases before registering — closing the PreShutdownCheck × // Hello TOCTOU race. The wait releases h.mu before blocking on the -// channel, so concurrent operations on other keys aren't stalled. +// channel, so concurrent operations on other subscriptions aren't stalled. func (h *Hub) RegisterAndIsFirst(s Subscriber) bool { + sid := s.SubscriptionID() for { h.mu.Lock() - ch, locked := h.cleanupInProgress[s.EventKey()] + ch, locked := h.cleanupInProgress[sid] if locked { h.mu.Unlock() <-ch // wait for release, then re-check (defensive against races) continue } - isFirst := h.keyCounts[s.EventKey()] == 0 + isFirst := h.subCounts[sid] == 0 h.subscribers[s] = struct{}{} - h.keyCounts[s.EventKey()]++ + h.subCounts[sid]++ h.mu.Unlock() return isFirst } @@ -176,11 +184,25 @@ func (h *Hub) ConnCount() int { return len(h.subscribers) } -// EventKeyCount returns the number of subscribers registered for eventKey. +// EventKeyCount returns total subscribers for the given EventKey, aggregating +// across all SubscriptionIDs. For per-subscription counts use SubCount. func (h *Hub) EventKeyCount(eventKey string) int { h.mu.RLock() defer h.mu.RUnlock() - return h.keyCounts[eventKey] + count := 0 + for s := range h.subscribers { + if s.EventKey() == eventKey { + count++ + } + } + return count +} + +// SubCount returns the count of subscribers for the given SubscriptionID. +func (h *Hub) SubCount(subscriptionID string) int { + h.mu.RLock() + defer h.mu.RUnlock() + return h.subCounts[subscriptionID] } // BroadcastSourceStatus fans out a source-level status change to every @@ -205,10 +227,11 @@ func (h *Hub) Consumers() []protocol.ConsumerInfo { result := make([]protocol.ConsumerInfo, 0, len(h.subscribers)) for s := range h.subscribers { result = append(result, protocol.ConsumerInfo{ - PID: s.PID(), - EventKey: s.EventKey(), - Received: s.Received(), - Dropped: s.DroppedCount(), + PID: s.PID(), + EventKey: s.EventKey(), + SubscriptionID: s.SubscriptionID(), + Received: s.Received(), + Dropped: s.DroppedCount(), }) } return result diff --git a/internal/event/bus/hub_publish_race_test.go b/internal/event/bus/hub_publish_race_test.go index b91987f5d..f0eb08661 100644 --- a/internal/event/bus/hub_publish_race_test.go +++ b/internal/event/bus/hub_publish_race_test.go @@ -111,6 +111,7 @@ type alwaysFailSubscriber struct { } func (s *alwaysFailSubscriber) EventKey() string { return s.eventKey } +func (s *alwaysFailSubscriber) SubscriptionID() string { return s.eventKey } func (s *alwaysFailSubscriber) EventTypes() []string { return s.eventTypes } func (s *alwaysFailSubscriber) SendCh() chan interface{} { return s.sendCh } func (s *alwaysFailSubscriber) PID() int { return 0 } @@ -153,6 +154,7 @@ func newRaceSubscriber(key string, types []string, capacity int) *raceSubscriber } func (s *raceSubscriber) EventKey() string { return s.eventKey } +func (s *raceSubscriber) SubscriptionID() string { return s.eventKey } func (s *raceSubscriber) EventTypes() []string { return s.eventTypes } func (s *raceSubscriber) SendCh() chan interface{} { return s.sendCh } func (s *raceSubscriber) PID() int { return s.pid } diff --git a/internal/event/bus/hub_test.go b/internal/event/bus/hub_test.go index e135d436c..6de5ff539 100644 --- a/internal/event/bus/hub_test.go +++ b/internal/event/bus/hub_test.go @@ -5,6 +5,7 @@ package bus import ( "encoding/json" + "net" "sync" "sync/atomic" "testing" @@ -235,8 +236,11 @@ func newTestConn(eventKey string, eventTypes []string) *testConn { } } -func (c *testConn) EventKey() string { return c.eventKey } -func (c *testConn) EventTypes() []string { return c.eventTypes } +func (c *testConn) EventKey() string { return c.eventKey } + +// SubscriptionID falls back to EventKey for test mocks that don't set a separate subscription ID. +func (c *testConn) SubscriptionID() string { return c.eventKey } +func (c *testConn) EventTypes() []string { return c.eventTypes } func (c *testConn) SendCh() chan interface{} { return c.sendCh } func (c *testConn) PID() int { return c.pid } func (c *testConn) IncrementReceived() { c.received.Add(1) } @@ -275,3 +279,79 @@ func (c *testConn) TrySend(msg interface{}) bool { return false } } + +func TestHub_SubscriptionID_Isolation(t *testing.T) { + h := NewHub() + c1, _ := net.Pipe() + c2, _ := net.Pipe() + defer c1.Close() + defer c2.Close() + s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice") + s2 := NewConn(c2, nil, "mail.x", []string{"mail.x"}, 2, "mail.x:bob") + + if !h.RegisterAndIsFirst(s1) { + t.Error("s1 should be first for its subscription") + } + if !h.RegisterAndIsFirst(s2) { + t.Error("s2 should ALSO be first (different SubscriptionID)") + } + if !h.UnregisterAndIsLast(s1) { + t.Error("s1 should be last for mail.x:alice") + } + if !h.UnregisterAndIsLast(s2) { + t.Error("s2 should be last for mail.x:bob") + } +} + +func TestHub_SameSubscriptionID_NotFirst(t *testing.T) { + h := NewHub() + c1, _ := net.Pipe() + c2, _ := net.Pipe() + defer c1.Close() + defer c2.Close() + s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice") + s2 := NewConn(c2, nil, "mail.x", []string{"mail.x"}, 2, "mail.x:alice") + + if !h.RegisterAndIsFirst(s1) { + t.Error("s1 first") + } + if h.RegisterAndIsFirst(s2) { + t.Error("s2 same SubscriptionID should NOT be first") + } +} + +func TestHub_EventKeyCount_AggregatesAcrossSubscriptions(t *testing.T) { + h := NewHub() + c1, _ := net.Pipe() + c2, _ := net.Pipe() + defer c1.Close() + defer c2.Close() + s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice") + s2 := NewConn(c2, nil, "mail.x", []string{"mail.x"}, 2, "mail.x:bob") + h.RegisterAndIsFirst(s1) + h.RegisterAndIsFirst(s2) + if got := h.EventKeyCount("mail.x"); got != 2 { + t.Errorf("EventKeyCount(mail.x) = %d, want 2 (aggregated across subscriptions)", got) + } + if got := h.SubCount("mail.x:alice"); got != 1 { + t.Errorf("SubCount(mail.x:alice) = %d, want 1", got) + } + if got := h.SubCount("mail.x:bob"); got != 1 { + t.Errorf("SubCount(mail.x:bob) = %d, want 1", got) + } +} + +func TestHub_Consumers_PopulatesSubscriptionID(t *testing.T) { + h := NewHub() + c1, _ := net.Pipe() + defer c1.Close() + s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice") + h.RegisterAndIsFirst(s1) + consumers := h.Consumers() + if len(consumers) != 1 { + t.Fatalf("got %d consumers, want 1", len(consumers)) + } + if consumers[0].SubscriptionID != "mail.x:alice" { + t.Errorf("Consumers()[0].SubscriptionID = %q, want %q", consumers[0].SubscriptionID, "mail.x:alice") + } +} From 6ee4ba0bfc37a3edbc44a10b9df579816daf9be6 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:13:43 +0800 Subject: [PATCH 06/24] test(event/bus): cover handleHello legacy vs modern SubscriptionID paths Change-Id: Ieb7c2237621a84721b6fc73967838d9caec2a837 --- internal/event/bus/handle_hello_test.go | 134 ++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/internal/event/bus/handle_hello_test.go b/internal/event/bus/handle_hello_test.go index 7be844dea..ab6e3fe2d 100644 --- a/internal/event/bus/handle_hello_test.go +++ b/internal/event/bus/handle_hello_test.go @@ -63,3 +63,137 @@ func TestHandleHello_HelloAckWriteFailureUnregisters(t *testing.T) { t.Errorf("b.conns after failed HelloAck = %d entries, want 0", remaining) } } + +// TestHandleHello_LegacyClient_FallsBackToEventKey: a Hello with empty +// subscription_id registers under EventKey (today's behavior preserved). +func TestHandleHello_LegacyClient_FallsBackToEventKey(t *testing.T) { + logger := log.New(io.Discard, "", 0) + hub := NewHub() + b := &Bus{ + hub: hub, + logger: logger, + conns: make(map[*Conn]struct{}), + idleTimer: time.NewTimer(30 * time.Second), + shutdownCh: make(chan struct{}, 1), + } + + server, client := net.Pipe() + defer server.Close() + defer client.Close() + + // Legacy client: no subscription_id field (empty string). + hello := &protocol.Hello{ + PID: 9999, + EventKey: "im.message", + EventTypes: []string{"im.message.receive_v1"}, + SubscriptionID: "", // legacy: empty, should fallback to EventKey + } + + br := bufio.NewReader(server) + + done := make(chan struct{}) + go func() { + b.handleHello(server, br, hello) + close(done) + }() + + // Read the HelloAck from client side to let handleHello complete. + clientReader := bufio.NewReader(client) + ackLine, err := clientReader.ReadString('\n') + if err != nil { + t.Fatalf("failed to read HelloAck: %v", err) + } + + select { + case <-done: + case <-time.After(3 * time.Second): + t.Fatal("handleHello did not return within 3s") + } + + // Assertions: registered under EventKey (not a qualified subscription ID). + if got := hub.ConnCount(); got != 1 { + t.Errorf("hub.ConnCount = %d, want 1", got) + } + if got := hub.EventKeyCount("im.message"); got != 1 { + t.Errorf("hub.EventKeyCount(im.message) = %d, want 1", got) + } + // Should be registered under the EventKey itself (fallback behavior). + if got := hub.SubCount("im.message"); got != 1 { + t.Errorf("hub.SubCount(im.message) = %d, want 1 (legacy fallback to EventKey)", got) + } + if got := hub.SubCount("im.message:something"); got != 0 { + t.Errorf("hub.SubCount(im.message:something) = %d, want 0 (should not exist)", got) + } + + if ackLine == "" { + t.Fatal("HelloAck was empty") + } +} + +// TestHandleHello_ModernClient_UsesSubscriptionID: a Hello with +// non-empty subscription_id registers under that ID, not EventKey. +func TestHandleHello_ModernClient_UsesSubscriptionID(t *testing.T) { + logger := log.New(io.Discard, "", 0) + hub := NewHub() + b := &Bus{ + hub: hub, + logger: logger, + conns: make(map[*Conn]struct{}), + idleTimer: time.NewTimer(30 * time.Second), + shutdownCh: make(chan struct{}, 1), + } + + server, client := net.Pipe() + defer server.Close() + defer client.Close() + + // Modern client: subscription_id explicitly set. + subscriptionID := "mail.message:alice@example.com" + hello := &protocol.Hello{ + PID: 8888, + EventKey: "mail.message", + EventTypes: []string{"mail.message.receive_v1"}, + SubscriptionID: subscriptionID, // modern: per-resource subscription + } + + br := bufio.NewReader(server) + + done := make(chan struct{}) + go func() { + b.handleHello(server, br, hello) + close(done) + }() + + // Read the HelloAck from client side to let handleHello complete. + clientReader := bufio.NewReader(client) + ackLine, err := clientReader.ReadString('\n') + if err != nil { + t.Fatalf("failed to read HelloAck: %v", err) + } + + select { + case <-done: + case <-time.After(3 * time.Second): + t.Fatal("handleHello did not return within 3s") + } + + // Assertions: registered under the subscription_id, not bare EventKey. + if got := hub.ConnCount(); got != 1 { + t.Errorf("hub.ConnCount = %d, want 1", got) + } + if got := hub.EventKeyCount("mail.message"); got != 1 { + t.Errorf("hub.EventKeyCount(mail.message) = %d, want 1", got) + } + // Should be registered under the full subscription ID. + if got := hub.SubCount(subscriptionID); got != 1 { + t.Errorf("hub.SubCount(%q) = %d, want 1 (modern: uses SubscriptionID)", subscriptionID, got) + } + // Should NOT be registered under bare EventKey. + if got := hub.SubCount("mail.message"); got != 0 { + t.Errorf("hub.SubCount(mail.message) = %d, want 0 (modern: NOT registered under bare EventKey)", got) + } + + if ackLine == "" { + t.Fatal("HelloAck was empty") + } +} From 66e566d81f7aac6e5d2f4855d6686d00f8ac4d63 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:16:57 +0800 Subject: [PATCH 07/24] feat(event/consume): wire NormalizeParams + ComputeSubscriptionID into Run Change-Id: Ifd43aa2a82c315ad3d496a39ce9f0dbdd43f3bb8 --- internal/event/consume/consume.go | 14 +++- internal/event/consume/consume_test.go | 97 ++++++++++++++++++++++++ internal/event/consume/handshake.go | 4 +- internal/event/consume/handshake_test.go | 2 +- 4 files changed, 113 insertions(+), 4 deletions(-) create mode 100644 internal/event/consume/consume_test.go diff --git a/internal/event/consume/consume.go b/internal/event/consume/consume.go index cb39ef6d5..b5c494aa0 100644 --- a/internal/event/consume/consume.go +++ b/internal/event/consume/consume.go @@ -58,6 +58,18 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin } } + // Normalize params (resolve aliases like "me" -> real email) before fingerprint + // compute, PreConsume, Match, Process. Must happen BEFORE doHello so the + // SubscriptionID we send to bus reflects canonical values. + if keyDef.NormalizeParams != nil { + if err := keyDef.NormalizeParams(ctx, opts.Runtime, opts.Params); err != nil { + return fmt.Errorf("normalize params for %s: %w", opts.EventKey, err) + } + } + + // Compute subscription identity from normalized params + SubscriptionKey flags. + subscriptionID := ComputeSubscriptionID(keyDef, opts.Params) + if opts.Timeout > 0 { var cancel context.CancelFunc ctx, cancel = context.WithTimeout(ctx, opts.Timeout) @@ -78,7 +90,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin } defer conn.Close() - ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType}) + ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType}, subscriptionID) if err != nil { return fmt.Errorf("handshake failed: %w", err) } diff --git a/internal/event/consume/consume_test.go b/internal/event/consume/consume_test.go new file mode 100644 index 000000000..00e18c079 --- /dev/null +++ b/internal/event/consume/consume_test.go @@ -0,0 +1,97 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package consume + +// NOTE: Run() requires bus daemon + transport infrastructure. Testing the full +// Run path end-to-end is complex. For this task we test the parts: +// (a) NormalizeParams error wrapping +// (b) doHello correctly threads subscriptionID through to the Hello message. + +import ( + "bufio" + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "net" + "strings" + "testing" + + "github.com/larksuite/cli/internal/event" + "github.com/larksuite/cli/internal/event/protocol" +) + +// fakeRT is a minimal event.APIClient mock. +type fakeRT struct { + err error +} + +func (f *fakeRT) CallAPI(_ context.Context, _, _ string, _ interface{}) (json.RawMessage, error) { + return nil, f.err +} + +func TestNormalizeParams_ErrorIsWrappedWithEventKey(t *testing.T) { + // We test the error wrapping pattern in isolation: same call site Run uses. + keyDef := &event.KeyDefinition{ + Key: "test.evt_normalize_fail", + NormalizeParams: func(_ context.Context, _ event.APIClient, _ map[string]string) error { + return errors.New("simulated normalize failure") + }, + } + err := keyDef.NormalizeParams(context.Background(), &fakeRT{}, map[string]string{}) + if err == nil { + t.Fatal("expected error from NormalizeParams") + } + // Run wraps with: fmt.Errorf("normalize params for %s: %w", EventKey, err) + wrapped := fmt.Errorf("normalize params for %s: %w", keyDef.Key, err) + if !strings.Contains(wrapped.Error(), "normalize params for test.evt_normalize_fail:") { + t.Errorf("wrap format wrong: %v", wrapped) + } + if !strings.Contains(wrapped.Error(), "simulated normalize failure") { + t.Errorf("underlying error not propagated: %v", wrapped) + } +} + +func TestDoHello_PassesSubscriptionIDToWire(t *testing.T) { + a, b := net.Pipe() + defer a.Close() + defer b.Close() + + // Server-side: read Hello, decode, assert SubscriptionID, send ack + done := make(chan string, 1) + go func() { + br := bufio.NewReader(b) + line, err := protocol.ReadFrame(br) + if err != nil { + done <- "READ_ERR:" + err.Error() + return + } + msg, err := protocol.Decode(bytes.TrimRight(line, "\n")) + if err != nil { + done <- "DECODE_ERR:" + err.Error() + return + } + if hello, ok := msg.(*protocol.Hello); ok { + done <- hello.SubscriptionID + // send ack so client can return + ack := protocol.NewHelloAck("v1", true) + _ = protocol.EncodeWithDeadline(b, ack, protocol.WriteTimeout) + } else { + done <- "WRONG_TYPE" + } + }() + + ack, _, err := doHello(a, "mail.x", []string{"mail.x"}, "mail.x:alice") + if err != nil { + t.Fatalf("doHello error: %v", err) + } + if ack == nil { + t.Fatal("got nil ack") + } + got := <-done + if got != "mail.x:alice" { + t.Errorf("Hello.SubscriptionID on wire = %q, want %q", got, "mail.x:alice") + } +} diff --git a/internal/event/consume/handshake.go b/internal/event/consume/handshake.go index 5994d8e38..18aeac959 100644 --- a/internal/event/consume/handshake.go +++ b/internal/event/consume/handshake.go @@ -18,8 +18,8 @@ const helloAckTimeout = 5 * time.Second // symmetric with bus-side hello read de // doHello returns a bufio.Reader holding any bytes already pulled off conn so events // buffered with the ack in one TCP segment aren't dropped. -func doHello(conn net.Conn, eventKey string, eventTypes []string) (*protocol.HelloAck, *bufio.Reader, error) { - hello := protocol.NewHello(os.Getpid(), eventKey, eventTypes, "v1", "") +func doHello(conn net.Conn, eventKey string, eventTypes []string, subscriptionID string) (*protocol.HelloAck, *bufio.Reader, error) { + hello := protocol.NewHello(os.Getpid(), eventKey, eventTypes, "v1", subscriptionID) if err := protocol.EncodeWithDeadline(conn, hello, protocol.WriteTimeout); err != nil { return nil, nil, err } diff --git a/internal/event/consume/handshake_test.go b/internal/event/consume/handshake_test.go index b434a9a97..918c849e6 100644 --- a/internal/event/consume/handshake_test.go +++ b/internal/event/consume/handshake_test.go @@ -27,7 +27,7 @@ func TestDoHello_ReadDeadline(t *testing.T) { start := time.Now() done := make(chan error, 1) go func() { - _, _, err := doHello(client, "im.msg", []string{"im.msg"}) + _, _, err := doHello(client, "im.msg", []string{"im.msg"}, "") done <- err }() From fe4622dab7d87dbbf88b92874706cba2a6ba09de Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:21:34 +0800 Subject: [PATCH 08/24] feat(event/consume): plumb SubscriptionID through checkLastForKey/consumeLoop Change-Id: Ib40b148c45f546ca112d30976749f42fae1f877a --- internal/event/consume/consume.go | 2 +- internal/event/consume/loop.go | 4 +-- internal/event/consume/loop_test.go | 8 ++--- internal/event/consume/shutdown.go | 4 +-- internal/event/consume/shutdown_test.go | 44 +++++++++++++++++++++++-- 5 files changed, 50 insertions(+), 12 deletions(-) diff --git a/internal/event/consume/consume.go b/internal/event/consume/consume.go index b5c494aa0..ee3a94640 100644 --- a/internal/event/consume/consume.go +++ b/internal/event/consume/consume.go @@ -148,7 +148,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin writeReadyMarker(errOut, opts) - return consumeLoop(ctx, conn, br, keyDef, opts, &lastForKey, &emitted) + return consumeLoop(ctx, conn, br, keyDef, opts, subscriptionID, &lastForKey, &emitted) } func truncateDuration(d time.Duration) time.Duration { diff --git a/internal/event/consume/loop.go b/internal/event/consume/loop.go index 6a3f844ca..5622c614e 100644 --- a/internal/event/consume/loop.go +++ b/internal/event/consume/loop.go @@ -22,7 +22,7 @@ import ( ) // consumeLoop reads events and dispatches to workers; cancels on terminal sink errors. -func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *event.KeyDefinition, opts Options, lastForKey *bool, emitted *atomic.Int64) error { +func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *event.KeyDefinition, opts Options, subscriptionID string, lastForKey *bool, emitted *atomic.Int64) error { ctx, cancel := context.WithCancel(ctx) defer cancel() @@ -185,7 +185,7 @@ func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *e close(stopReader) <-readerDone conn.SetReadDeadline(time.Time{}) - *lastForKey = checkLastForKey(conn, opts.EventKey) + *lastForKey = checkLastForKey(conn, opts.EventKey, subscriptionID) conn.Close() case <-allDone: // bus-side close; can't query, assume last diff --git a/internal/event/consume/loop_test.go b/internal/event/consume/loop_test.go index 9b098da7f..1f656646a 100644 --- a/internal/event/consume/loop_test.go +++ b/internal/event/consume/loop_test.go @@ -89,7 +89,7 @@ func TestConsumeLoop_DeliversEventsAndExitsOnMaxEvents(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() - err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted) + err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted) if err != nil { t.Fatalf("consumeLoop: %v", err) } @@ -132,7 +132,7 @@ func TestConsumeLoop_SeqGapEmitsWarning(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() - if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted); err != nil { + if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted); err != nil { t.Fatalf("consumeLoop: %v", err) } if got := emitted.Load(); got != 2 { @@ -169,7 +169,7 @@ func TestConsumeLoop_JQFilterAppliedPerEvent(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() - if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted); err != nil { + if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted); err != nil { t.Fatalf("consumeLoop: %v", err) } if got := emitted.Load(); got != 1 { @@ -196,7 +196,7 @@ func TestConsumeLoop_CompileJQFailsEarly(t *testing.T) { var lastForKey bool var emitted atomic.Int64 - err := consumeLoop(context.Background(), client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted) + err := consumeLoop(context.Background(), client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted) if err == nil { t.Fatal("consumeLoop should fail immediately on bad jq expression") } diff --git a/internal/event/consume/shutdown.go b/internal/event/consume/shutdown.go index b54abf2b0..3c07f9869 100644 --- a/internal/event/consume/shutdown.go +++ b/internal/event/consume/shutdown.go @@ -16,8 +16,8 @@ const preShutdownAckTimeout = 2 * time.Second // checkLastForKey atomically reserves a cleanup lock; on any error defaults to true // (cleanup-on-error is safer than leaking server state). Discards non-ack frames in flight. -func checkLastForKey(conn net.Conn, eventKey string) bool { - msg := protocol.NewPreShutdownCheck(eventKey, "") +func checkLastForKey(conn net.Conn, eventKey string, subscriptionID string) bool { + msg := protocol.NewPreShutdownCheck(eventKey, subscriptionID) if err := protocol.EncodeWithDeadline(conn, msg, protocol.WriteTimeout); err != nil { return true } diff --git a/internal/event/consume/shutdown_test.go b/internal/event/consume/shutdown_test.go index c77754a49..76e28ad66 100644 --- a/internal/event/consume/shutdown_test.go +++ b/internal/event/consume/shutdown_test.go @@ -4,6 +4,8 @@ package consume import ( + "bufio" + "bytes" "encoding/json" "io" "net" @@ -38,7 +40,7 @@ func TestCheckLastForKey_IgnoresNonAckFrames(t *testing.T) { } }() - got := checkLastForKey(client, "im.msg") + got := checkLastForKey(client, "im.msg", "") if got != false { t.Errorf("checkLastForKey = %v, want false", got) } @@ -62,7 +64,7 @@ func TestCheckLastForKey_ReturnsAckValue(t *testing.T) { _ = protocol.Encode(server, ack) }() - got := checkLastForKey(client, "im.msg") + got := checkLastForKey(client, "im.msg", "") if got != true { t.Errorf("checkLastForKey = %v, want true", got) } @@ -83,7 +85,7 @@ func TestCheckLastForKey_DefaultsToTrueOnTimeout(t *testing.T) { }() start := time.Now() - got := checkLastForKey(client, "im.msg") + got := checkLastForKey(client, "im.msg", "") elapsed := time.Since(start) if got != true { @@ -93,3 +95,39 @@ func TestCheckLastForKey_DefaultsToTrueOnTimeout(t *testing.T) { t.Errorf("elapsed = %v, expected ~%v (timeout-bounded)", elapsed, preShutdownAckTimeout) } } + +func TestCheckLastForKey_SendsSubscriptionID(t *testing.T) { + a, b := net.Pipe() + defer a.Close() + defer b.Close() + + done := make(chan string, 1) + go func() { + br := bufio.NewReader(b) + line, err := protocol.ReadFrame(br) + if err != nil { + done <- "READ_ERR" + return + } + msg, err := protocol.Decode(bytes.TrimRight(line, "\n")) + if err != nil { + done <- "DECODE_ERR" + return + } + check, ok := msg.(*protocol.PreShutdownCheck) + if !ok { + done <- "WRONG_TYPE" + return + } + done <- check.SubscriptionID + // Reply with ack so client returns + ack := protocol.NewPreShutdownAck(true) + _ = protocol.EncodeWithDeadline(b, ack, protocol.WriteTimeout) + }() + + _ = checkLastForKey(a, "mail.x", "mail.x:alice") + got := <-done + if got != "mail.x:alice" { + t.Errorf("PreShutdownCheck.SubscriptionID on wire = %q, want %q", got, "mail.x:alice") + } +} From 279c9f528bb9e691ae22be3c1ed4ee3255871192 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:24:43 +0800 Subject: [PATCH 09/24] feat(event/consume): surface cleanup errors as WARN with idempotency note Change-Id: I121ec0d3e7d50f3ebb728f47f1f54d89322e0143 --- internal/event/consume/consume.go | 16 ++++++++++++---- internal/event/consume/consume_test.go | 12 ++++++++++++ 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/internal/event/consume/consume.go b/internal/event/consume/consume.go index ee3a94640..95e0910e4 100644 --- a/internal/event/consume/consume.go +++ b/internal/event/consume/consume.go @@ -117,14 +117,22 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin if cleanup != nil { switch { case r != nil: - fmt.Fprintf(errOut, "WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n", opts.EventKey) - _ = cleanup() // proper error handling added in Task 9 + fmt.Fprintf(errOut, + "WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n", + opts.EventKey) + if cleanupErr := cleanup(); cleanupErr != nil { + fmt.Fprintf(errOut, + "WARN: cleanup also failed during panic recovery: %v\n", cleanupErr) + } case lastForKey: if !opts.Quiet { fmt.Fprintf(errOut, "[event] running cleanup...\n") } - _ = cleanup() // proper error handling added in Task 9 - if !opts.Quiet { + if cleanupErr := cleanup(); cleanupErr != nil { + fmt.Fprintf(errOut, + "WARN: cleanup failed: %v (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)\n", + cleanupErr) + } else if !opts.Quiet { fmt.Fprintf(errOut, "[event] cleanup done.\n") } } diff --git a/internal/event/consume/consume_test.go b/internal/event/consume/consume_test.go index 00e18c079..9f11e644c 100644 --- a/internal/event/consume/consume_test.go +++ b/internal/event/consume/consume_test.go @@ -95,3 +95,15 @@ func TestDoHello_PassesSubscriptionIDToWire(t *testing.T) { t.Errorf("Hello.SubscriptionID on wire = %q, want %q", got, "mail.x:alice") } } + +func TestCleanupErrorBranching_Format(t *testing.T) { + // Unit-level check of the message format. We don't run full Run() — too + // much wiring. Instead we verify the format string is correct by checking + // the literal we expect in stderr matches what the spec mandates. + want := "WARN: cleanup failed: simulated unsubscribe failure (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)" + got := fmt.Sprintf("WARN: cleanup failed: %v (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)", + errors.New("simulated unsubscribe failure")) + if got != want { + t.Errorf("format mismatch:\n got: %s\nwant: %s", got, want) + } +} From d98ff47c25af55fe46065647c1d006027df0d2fe Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:28:19 +0800 Subject: [PATCH 10/24] feat(event/consume): add sync Match filter before Process Run keyDef.Match(raw, params) at the top of processAndOutput before any Process/sink work; drop the event (return false, nil) when it returns false. Move the RawEvent allocation above the Match guard so both Match and Process share the same struct. Three new unit tests cover drop, nil-accepts-all, and run-before-process ordering. Change-Id: I21571b3da91a9a918903b6fc3a6ff897eb83a747 --- internal/event/consume/loop.go | 14 +++-- internal/event/consume/loop_test.go | 83 +++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 4 deletions(-) diff --git a/internal/event/consume/loop.go b/internal/event/consume/loop.go index 5622c614e..849caddd8 100644 --- a/internal/event/consume/loop.go +++ b/internal/event/consume/loop.go @@ -199,13 +199,19 @@ func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *e // processAndOutput returns (wrote, err); err non-nil only for sink.Write failures. func processAndOutput(ctx context.Context, keyDef *event.KeyDefinition, evt *protocol.Event, opts Options, sink Sink, jqCode *gojq.Code) (bool, error) { + raw := &event.RawEvent{ + EventType: evt.EventType, + Payload: evt.Payload, + } + + // Synchronous Match filter runs before any work (Process / sink write). + if keyDef.Match != nil && !keyDef.Match(raw, opts.Params) { + return false, nil + } + var result json.RawMessage if keyDef.Process != nil { - raw := &event.RawEvent{ - EventType: evt.EventType, - Payload: evt.Payload, - } var err error result, err = keyDef.Process(ctx, opts.Runtime, raw, opts.Params) if err != nil { diff --git a/internal/event/consume/loop_test.go b/internal/event/consume/loop_test.go index 1f656646a..9ce6270e4 100644 --- a/internal/event/consume/loop_test.go +++ b/internal/event/consume/loop_test.go @@ -202,6 +202,89 @@ func TestConsumeLoop_CompileJQFailsEarly(t *testing.T) { } } +// captureSink is a minimal Sink for unit-testing processAndOutput directly. +type captureSink struct { + written []json.RawMessage +} + +func (s *captureSink) Write(data json.RawMessage) error { + s.written = append(s.written, data) + return nil +} + +func TestProcessAndOutput_Match_DropsEvent(t *testing.T) { + calledProcess := false + keyDef := &event.KeyDefinition{ + Key: "test.evt", + Match: func(raw *event.RawEvent, params map[string]string) bool { + return false + }, + Process: func(ctx context.Context, rt event.APIClient, raw *event.RawEvent, params map[string]string) (json.RawMessage, error) { + calledProcess = true + return json.RawMessage(`{}`), nil + }, + } + sink := &captureSink{} + wrote, err := processAndOutput(context.Background(), keyDef, + &protocol.Event{Type: protocol.MsgTypeEvent, EventType: "test.evt", Payload: json.RawMessage(`{"x":1}`)}, + Options{}, sink, nil) + if err != nil { + t.Fatal(err) + } + if wrote { + t.Error("Match returned false but event was written") + } + if calledProcess { + t.Error("Process was called even though Match returned false") + } + if len(sink.written) != 0 { + t.Errorf("sink received %d events, want 0", len(sink.written)) + } +} + +func TestProcessAndOutput_Match_NilAcceptsAll(t *testing.T) { + keyDef := &event.KeyDefinition{Key: "test.evt"} // no Match, no Process + sink := &captureSink{} + wrote, err := processAndOutput(context.Background(), keyDef, + &protocol.Event{Type: protocol.MsgTypeEvent, EventType: "test.evt", Payload: json.RawMessage(`{"x":1}`)}, + Options{}, sink, nil) + if err != nil || !wrote { + t.Errorf("expected wrote=true err=nil; got wrote=%v err=%v", wrote, err) + } + if len(sink.written) != 1 { + t.Errorf("sink received %d events, want 1", len(sink.written)) + } +} + +func TestProcessAndOutput_Match_RunsBeforeProcess(t *testing.T) { + processCalls := 0 + matchCalls := 0 + keyDef := &event.KeyDefinition{ + Key: "test.evt", + Match: func(raw *event.RawEvent, params map[string]string) bool { + matchCalls++ + return true + }, + Process: func(ctx context.Context, rt event.APIClient, raw *event.RawEvent, params map[string]string) (json.RawMessage, error) { + processCalls++ + return raw.Payload, nil + }, + } + sink := &captureSink{} + wrote, err := processAndOutput(context.Background(), keyDef, + &protocol.Event{Type: protocol.MsgTypeEvent, EventType: "test.evt", Payload: json.RawMessage(`{}`)}, + Options{}, sink, nil) + if err != nil { + t.Fatal(err) + } + if !wrote { + t.Error("expected wrote=true") + } + if matchCalls != 1 || processCalls != 1 { + t.Errorf("match=%d process=%d, want 1/1", matchCalls, processCalls) + } +} + func TestIsTerminalSinkError(t *testing.T) { for _, tc := range []struct { name string From 224b9288f3338269c672b5b8deaee1d8358ec836 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:31:44 +0800 Subject: [PATCH 11/24] feat(cmd/event): render SubscriptionKey marker in schema output Change-Id: I2f88774c58719af0419c471f40de1bf12242a5ab --- cmd/event/schema.go | 8 +++-- cmd/event/schema_test.go | 73 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 2 deletions(-) diff --git a/cmd/event/schema.go b/cmd/event/schema.go index 830ce0566..abfa86e33 100644 --- a/cmd/event/schema.go +++ b/cmd/event/schema.go @@ -131,12 +131,16 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error { if len(def.Params) > 0 { fmt.Fprintf(out, "\nParameters:\n") w := tabwriter.NewWriter(out, 0, 4, 2, ' ', 0) - fmt.Fprintf(w, " NAME\tTYPE\tREQUIRED\tDEFAULT\tDESCRIPTION\n") + fmt.Fprintf(w, " NAME\tTYPE\tREQUIRED\tSUB-KEY\tDEFAULT\tDESCRIPTION\n") for _, p := range def.Params { required := "no" if p.Required { required = "yes" } + subKey := "no" + if p.SubscriptionKey { + subKey = "yes" + } defaultVal := p.Default if defaultVal == "" { defaultVal = "-" @@ -145,7 +149,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error { if desc == "" { desc = "-" } - fmt.Fprintf(w, " %s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, defaultVal, desc) + fmt.Fprintf(w, " %s\t%s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, subKey, defaultVal, desc) } w.Flush() diff --git a/cmd/event/schema_test.go b/cmd/event/schema_test.go index 3dc16a993..07be96da8 100644 --- a/cmd/event/schema_test.go +++ b/cmd/event/schema_test.go @@ -95,6 +95,79 @@ func TestRunSchema_JSONOutput(t *testing.T) { } } +func TestSchema_RendersSubscriptionKeyMarker(t *testing.T) { + const syntheticKey = "test.evt_sub" + t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) }) + + eventlib.RegisterKey(eventlib.KeyDefinition{ + Key: syntheticKey, + EventType: syntheticKey, + Params: []eventlib.ParamDef{ + {Name: "mailbox", SubscriptionKey: true, Description: "subscription id source"}, + {Name: "folders", Description: "filter only"}, + }, + Schema: eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}}, + }) + + f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"}) + if err := runSchema(f, syntheticKey, false); err != nil { + t.Fatalf("runSchema: %v", err) + } + + out := stdout.String() + if !strings.Contains(out, "SUB-KEY") { + t.Errorf("missing SUB-KEY column header in:\n%s", out) + } + + // Find the mailbox row and verify "yes" is present + var mailboxRow string + for _, ln := range strings.Split(out, "\n") { + if strings.Contains(ln, "mailbox") && !strings.Contains(ln, "NAME") { + mailboxRow = ln + break + } + } + if !strings.Contains(mailboxRow, "yes") { + t.Errorf("mailbox row missing yes SUB-KEY marker: %q", mailboxRow) + } + + // Find the folders row and verify "no" is present + var foldersRow string + for _, ln := range strings.Split(out, "\n") { + if strings.Contains(ln, "folders") && !strings.Contains(ln, "NAME") { + foldersRow = ln + break + } + } + if !strings.Contains(foldersRow, "no") { + t.Errorf("folders row missing no SUB-KEY marker: %q", foldersRow) + } +} + +func TestSchema_JSON_IncludesSubscriptionKey(t *testing.T) { + const syntheticKey = "test.evt_json" + t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) }) + + eventlib.RegisterKey(eventlib.KeyDefinition{ + Key: syntheticKey, + EventType: syntheticKey, + Params: []eventlib.ParamDef{{Name: "mailbox", SubscriptionKey: true}}, + Schema: eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}}, + }) + + f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"}) + if err := runSchema(f, syntheticKey, true); err != nil { + t.Fatalf("runSchema json: %v", err) + } + + if !strings.Contains(stdout.String(), `"subscription_key"`) { + t.Errorf("JSON output missing subscription_key field: %s", stdout.String()) + } + if !strings.Contains(stdout.String(), `true`) { + t.Errorf("JSON output missing subscription_key: true value: %s", stdout.String()) + } +} + func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) { const syntheticKey = "t.custom.overlay" t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) }) From 37bef6f3d351a630eeaca59707b19f48495acd81 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:35:36 +0800 Subject: [PATCH 12/24] feat(cmd/event): render SubscriptionID column in status table Add a SUB column to the human-readable consumer table in `event status`. Renders the fingerprint hash suffix (after the colon) when present; falls back to "-" for legacy consumers where SubscriptionID is empty or equal to EventKey. Change-Id: Ia6271475e562844fc275f3751c64ca408ebda82c --- cmd/event/format_helpers_test.go | 73 ++++++++++++++++++++++++++++++++ cmd/event/status.go | 12 +++++- 2 files changed, 84 insertions(+), 1 deletion(-) diff --git a/cmd/event/format_helpers_test.go b/cmd/event/format_helpers_test.go index 939b85d25..a9aaf694e 100644 --- a/cmd/event/format_helpers_test.go +++ b/cmd/event/format_helpers_test.go @@ -143,6 +143,79 @@ func TestWriteStatusText_CoversAllStates(t *testing.T) { } } +func TestWriteStatusText_ShowsSubColumn(t *testing.T) { + var buf bytes.Buffer + writeStatusText(&buf, []appStatus{ + { + AppID: "cli_RUNNINGXXXXXXXXX", + State: stateRunning, + PID: 1234, + UptimeSec: 60, + Active: 2, + Consumers: []protocol.ConsumerInfo{ + {PID: 1001, EventKey: "mail.x", SubscriptionID: "mail.x:alice", Received: 5, Dropped: 0}, + {PID: 1002, EventKey: "mail.x", SubscriptionID: "mail.x:bob", Received: 3, Dropped: 0}, + }, + }, + }) + out := buf.String() + if !strings.Contains(out, "SUB") { + t.Errorf("missing SUB column header: %s", out) + } + if !strings.Contains(out, "alice") { + t.Errorf("missing alice suffix in SUB column: %s", out) + } + if !strings.Contains(out, "bob") { + t.Errorf("missing bob suffix in SUB column: %s", out) + } +} + +func TestWriteStatusText_LegacySubscriptionID_RendersDash(t *testing.T) { + var buf bytes.Buffer + writeStatusText(&buf, []appStatus{ + { + AppID: "cli_RUNNINGXXXXXXXXX", + State: stateRunning, + PID: 1234, + UptimeSec: 60, + Active: 1, + Consumers: []protocol.ConsumerInfo{ + {PID: 1001, EventKey: "im.x", SubscriptionID: "", Received: 5}, + }, + }, + }) + out := buf.String() + if !strings.Contains(out, "SUB") { + t.Errorf("missing SUB header: %s", out) + } + if !strings.Contains(out, "-") { + t.Errorf("missing dash placeholder for empty SubscriptionID: %s", out) + } +} + +func TestWriteStatusText_EventKeyEqualSubscriptionID_RendersDash(t *testing.T) { + var buf bytes.Buffer + writeStatusText(&buf, []appStatus{ + { + AppID: "cli_RUNNINGXXXXXXXXX", + State: stateRunning, + PID: 1234, + UptimeSec: 60, + Active: 1, + Consumers: []protocol.ConsumerInfo{ + {PID: 1001, EventKey: "im.x", SubscriptionID: "im.x", Received: 5}, + }, + }, + }) + out := buf.String() + if !strings.Contains(out, "SUB") { + t.Errorf("missing SUB header: %s", out) + } + if !strings.Contains(out, "-") { + t.Errorf("missing dash placeholder when SubscriptionID==EventKey: %s", out) + } +} + func TestWriteStatusJSON_OrphanHint(t *testing.T) { var buf bytes.Buffer if err := writeStatusJSON(&buf, []appStatus{ diff --git a/cmd/event/status.go b/cmd/event/status.go index 92c8be25d..28e600f21 100644 --- a/cmd/event/status.go +++ b/cmd/event/status.go @@ -7,6 +7,7 @@ import ( "fmt" "io" "sort" + "strings" "sync" "time" @@ -242,12 +243,21 @@ func writeStatusText(out io.Writer, statuses []appStatus) { s.PID, (time.Duration(s.UptimeSec) * time.Second).String()) fmt.Fprintf(out, " Active consumers: %d\n", s.Active) if len(s.Consumers) > 0 { - headers := []string{"CONSUMER", "EVENT KEY", "RECEIVED", "DROPPED"} + headers := []string{"CONSUMER", "EVENT KEY", "SUB", "RECEIVED", "DROPPED"} rows := make([][]string, 0, len(s.Consumers)) for _, c := range s.Consumers { + subDisplay := "-" + if c.SubscriptionID != "" && c.SubscriptionID != c.EventKey { + if idx := strings.Index(c.SubscriptionID, ":"); idx >= 0 { + subDisplay = c.SubscriptionID[idx+1:] + } else { + subDisplay = c.SubscriptionID + } + } rows = append(rows, []string{ fmt.Sprintf("pid=%d", c.PID), c.EventKey, + subDisplay, fmt.Sprintf("%d", c.Received), fmt.Sprintf("%d", c.Dropped), }) From 5cfcf54a20c7db4aee0ae37e3593759f2453d093 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:38:27 +0800 Subject: [PATCH 13/24] feat(events/mail): add MailReceivedPayload union schema Change-Id: Ie880d12e5dda73925ccaadc60ff8d3acda401dd6 --- events/mail/payload.go | 43 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 events/mail/payload.go diff --git a/events/mail/payload.go b/events/mail/payload.go new file mode 100644 index 000000000..c9efb50c5 --- /dev/null +++ b/events/mail/payload.go @@ -0,0 +1,43 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +// Package mail registers Mail-domain EventKeys and supporting types. +package mail + +// MailReceivedPayload is the unified output schema for +// mail.user_mailbox.event.message_received_v1. Fields are populated +// conditionally based on the msg-format param; readers should treat +// absent fields as null/zero: +// +// - msg-format=event : MessageID, MailAddress, MailboxType, Subscriber +// - msg-format=metadata : event fields + From, Subject, Snippet, FolderID, LabelIDs +// - msg-format=plain_text_full : metadata fields + BodyText +// - msg-format=full : metadata + BodyText + BodyHTML + Attachments +type MailReceivedPayload struct { + // Always present (msg-format=event and above) + MessageID string `json:"message_id" desc:"Unique message identifier"` + MailAddress string `json:"mail_address" desc:"Recipient mailbox address (matches the subscribed mailbox)"` + MailboxType int `json:"mailbox_type" desc:"Mailbox type enum: 1=primary, 2=shared"` + Subscriber string `json:"subscriber" desc:"open_id of the user who owns the subscription"` + + // Populated when msg-format >= metadata + From string `json:"from,omitempty" desc:"Sender email address (msg-format >= metadata)"` + Subject string `json:"subject,omitempty" desc:"Mail subject (msg-format >= metadata)"` + Snippet string `json:"snippet,omitempty" desc:"Body preview, first ~100 chars (msg-format >= metadata)"` + FolderID string `json:"folder_id,omitempty" desc:"Folder ID containing this message (msg-format >= metadata)"` + LabelIDs []string `json:"label_ids,omitempty" desc:"Label IDs attached (msg-format >= metadata)"` + + // Populated when msg-format >= plain_text_full + BodyText string `json:"body_text,omitempty" desc:"Plain-text body (msg-format >= plain_text_full)"` + + // Populated when msg-format=full only + BodyHTML string `json:"body_html,omitempty" desc:"HTML body (msg-format=full only)"` + Attachments []MailAttachment `json:"attachments,omitempty" desc:"Attachment metadata (msg-format=full only)"` +} + +type MailAttachment struct { + AttachmentID string `json:"attachment_id" desc:"Attachment ID for fetch"` + Filename string `json:"filename" desc:"Original filename"` + SizeBytes int64 `json:"size_bytes" desc:"Size in bytes"` + ContentType string `json:"content_type" desc:"MIME type"` +} From 3688c1c7ba7e429033a04ede25888a7d4a937d18 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:39:55 +0800 Subject: [PATCH 14/24] feat(events/mail): add normalizeMailParams to resolve 'me' alias Change-Id: I02cca113d50067e9a5964b896b2bc84210d2a35b --- events/mail/normalize.go | 44 ++++++++++++++ events/mail/normalize_test.go | 107 ++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 events/mail/normalize.go create mode 100644 events/mail/normalize_test.go diff --git a/events/mail/normalize.go b/events/mail/normalize.go new file mode 100644 index 000000000..9ab0cf67b --- /dev/null +++ b/events/mail/normalize.go @@ -0,0 +1,44 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "context" + "encoding/json" + "fmt" + "strings" + + "github.com/larksuite/cli/internal/event" +) + +// normalizeMailParams resolves the mailbox alias "me" (or empty) into the +// user's real primary email so fingerprint / Match / Process all see the +// canonical value. +// +// API: GET /open-apis/mail/v1/user_mailboxes/me — returns {data:{email:"..."}} +// Verified via: lark-cli api GET /open-apis/mail/v1/user_mailboxes/me --as user +func normalizeMailParams(ctx context.Context, rt event.APIClient, params map[string]string) error { + mbox := strings.TrimSpace(params["mailbox"]) + if mbox == "" || mbox == "me" { + data, err := rt.CallAPI(ctx, "GET", "/open-apis/mail/v1/user_mailboxes/me", nil) + if err != nil { + return fmt.Errorf("resolve mailbox 'me': %w", err) + } + var parsed struct { + Data struct { + Email string `json:"email"` + } `json:"data"` + } + if err := json.Unmarshal(data, &parsed); err != nil { + return fmt.Errorf("decode user_mailboxes/me response: %w", err) + } + if parsed.Data.Email == "" { + return fmt.Errorf("user_mailboxes/me returned empty email") + } + params["mailbox"] = parsed.Data.Email + return nil + } + params["mailbox"] = mbox + return nil +} diff --git a/events/mail/normalize_test.go b/events/mail/normalize_test.go new file mode 100644 index 000000000..68fc58439 --- /dev/null +++ b/events/mail/normalize_test.go @@ -0,0 +1,107 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "context" + "encoding/json" + "errors" + "strings" + "testing" + + "github.com/larksuite/cli/internal/event" +) + +type fakeRT struct { + getMailboxResponse json.RawMessage + getMailboxErr error + gotPath string +} + +func (f *fakeRT) CallAPI(ctx context.Context, method, path string, body interface{}) (json.RawMessage, error) { + f.gotPath = path + if f.getMailboxErr != nil { + return nil, f.getMailboxErr + } + return f.getMailboxResponse, nil +} + +func TestNormalizeMailParams(t *testing.T) { + tests := []struct { + name string + input string + response json.RawMessage + responseErr error + wantOut string + wantErrSub string + wantAPICall bool + }{ + { + name: "me resolves to real email", + input: "me", + response: json.RawMessage(`{"data":{"email":"liuxinyang@example.com"}}`), + wantOut: "liuxinyang@example.com", + wantAPICall: true, + }, + { + name: "empty resolves to real email", + input: "", + response: json.RawMessage(`{"data":{"email":"liuxinyang@example.com"}}`), + wantOut: "liuxinyang@example.com", + wantAPICall: true, + }, + { + name: "trim whitespace, no API call", + input: " user@example.com ", + wantOut: "user@example.com", + wantAPICall: false, + }, + { + name: "explicit email passes through", + input: "user@example.com", + wantOut: "user@example.com", + wantAPICall: false, + }, + { + name: "API error wraps with context", + input: "me", + responseErr: errors.New("network down"), + wantErrSub: "resolve mailbox 'me': network down", + }, + { + name: "empty email in response is error", + input: "me", + response: json.RawMessage(`{"data":{"email":""}}`), + wantErrSub: "empty email", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + rt := &fakeRT{getMailboxResponse: tt.response, getMailboxErr: tt.responseErr} + params := map[string]string{"mailbox": tt.input} + err := normalizeMailParams(context.Background(), rt, params) + if tt.wantErrSub != "" { + if err == nil || !strings.Contains(err.Error(), tt.wantErrSub) { + t.Errorf("want error containing %q, got %v", tt.wantErrSub, err) + } + return + } + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if params["mailbox"] != tt.wantOut { + t.Errorf("got mailbox=%q want %q", params["mailbox"], tt.wantOut) + } + if tt.wantAPICall && rt.gotPath == "" { + t.Error("expected API call but none made") + } + if !tt.wantAPICall && rt.gotPath != "" { + t.Errorf("unexpected API call to %s", rt.gotPath) + } + }) + } +} + +// Compile-time: normalizeMailParams must match the NormalizeParams signature. +var _ func(context.Context, event.APIClient, map[string]string) error = normalizeMailParams From a5f6ae14c6f53a464d8f1d3ac8edc6bc821ea22a Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:40:41 +0800 Subject: [PATCH 15/24] feat(events/mail): add matchMailbox sync filter Change-Id: I3dcd481fa93ce8f5dbde1e065aa00c18330265c0 --- events/mail/match.go | 35 +++++++++++++++++++++++ events/mail/match_test.go | 59 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 events/mail/match.go create mode 100644 events/mail/match_test.go diff --git a/events/mail/match.go b/events/mail/match.go new file mode 100644 index 000000000..38368a60a --- /dev/null +++ b/events/mail/match.go @@ -0,0 +1,35 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "encoding/json" + + "github.com/larksuite/cli/internal/event" +) + +// matchMailbox compares the V2-envelope payload's event.mail_address against +// the normalized params.mailbox. Drops events whose mail_address doesn't match. +// +// Fail-open policy: if params.mailbox is empty (no filter), or payload can't +// be parsed (defensive — upstream schema may evolve), accept the event rather +// than silently dropping legitimate traffic. +// +// IMPORTANT: caller must ensure params.mailbox is already normalized to a real +// email (not "me"). normalizeMailParams handles this. +func matchMailbox(raw *event.RawEvent, params map[string]string) bool { + target := params["mailbox"] + if target == "" { + return true + } + var env struct { + Event struct { + MailAddress string `json:"mail_address"` + } `json:"event"` + } + if err := json.Unmarshal(raw.Payload, &env); err != nil { + return true // fail-open + } + return env.Event.MailAddress == target +} diff --git a/events/mail/match_test.go b/events/mail/match_test.go new file mode 100644 index 000000000..6d9c16e19 --- /dev/null +++ b/events/mail/match_test.go @@ -0,0 +1,59 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "encoding/json" + "testing" + + "github.com/larksuite/cli/internal/event" +) + +func TestMatchMailbox(t *testing.T) { + makeV2Envelope := func(mailAddr string) json.RawMessage { + return json.RawMessage(`{"schema":"2.0","header":{},"event":{"mail_address":"` + mailAddr + `"}}`) + } + tests := []struct { + name string + payload json.RawMessage + params map[string]string + want bool + }{ + { + name: "exact match", + payload: makeV2Envelope("alice@example.com"), + params: map[string]string{"mailbox": "alice@example.com"}, + want: true, + }, + { + name: "mismatch drops", + payload: makeV2Envelope("bob@example.com"), + params: map[string]string{"mailbox": "alice@example.com"}, + want: false, + }, + { + name: "empty params accepts all (fail-open: no filter)", + payload: makeV2Envelope("anything@example.com"), + params: map[string]string{}, + want: true, + }, + { + name: "malformed payload fail-open", + payload: json.RawMessage(`not json`), + params: map[string]string{"mailbox": "alice@example.com"}, + want: true, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + raw := &event.RawEvent{Payload: tt.payload} + if got := matchMailbox(raw, tt.params); got != tt.want { + t.Errorf("got %v, want %v", got, tt.want) + } + }) + } +} + +// Compile-time: matchMailbox must match the Match signature. +var _ func(*event.RawEvent, map[string]string) bool = matchMailbox From c7bb890bd230e5dfee4deb7230b2792de955bb12 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:42:58 +0800 Subject: [PATCH 16/24] feat(events/mail): add processMailEvent for filter + format enrichment Change-Id: I99c64618900dde0b5420ce8a4f5c088960098e66 --- events/mail/process.go | 168 ++++++++++++++++++++++++ events/mail/process_test.go | 247 ++++++++++++++++++++++++++++++++++++ 2 files changed, 415 insertions(+) create mode 100644 events/mail/process.go create mode 100644 events/mail/process_test.go diff --git a/events/mail/process.go b/events/mail/process.go new file mode 100644 index 000000000..37e39fb71 --- /dev/null +++ b/events/mail/process.go @@ -0,0 +1,168 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "context" + "encoding/json" + "fmt" + "net/url" + "strings" + + "github.com/larksuite/cli/internal/event" +) + +// processMailEvent enriches and optionally drops a mail event based on params: +// - msg-format: determines fetch depth (event/metadata/plain_text_full/full) +// - folders, labels: drop events whose mail metadata doesn't match +// +// Returns (nil, nil) to signal the framework "drop this event". +// Returns (nil, err) on transport / parsing errors that should bubble up. +func processMailEvent(ctx context.Context, rt event.APIClient, raw *event.RawEvent, params map[string]string) (json.RawMessage, error) { + envFields, err := extractEventFields(raw.Payload) + if err != nil { + return nil, fmt.Errorf("decode mail event envelope: %w", err) + } + + payload := MailReceivedPayload{ + MessageID: envFields.MessageID, + MailAddress: envFields.MailAddress, + MailboxType: envFields.MailboxType, + Subscriber: envFields.Subscriber, + } + + msgFormat := params["msg-format"] + if msgFormat == "" { + msgFormat = "event" + } + + folders := splitCSV(params["folders"]) + labels := splitCSV(params["labels"]) + needFetch := msgFormat != "event" || len(folders) > 0 || len(labels) > 0 + + if !needFetch { + return json.Marshal(payload) + } + + fetchFormat := "metadata" + if msgFormat == "plain_text_full" { + fetchFormat = "plain_text_full" + } else if msgFormat == "full" { + fetchFormat = "full" + } + mailbox := params["mailbox"] + if mailbox == "" { + return nil, fmt.Errorf("mailbox param required for fetch (msg-format=%s)", msgFormat) + } + + path := fmt.Sprintf("/open-apis/mail/v1/user_mailboxes/%s/messages/%s?format=%s", + url.PathEscape(mailbox), url.PathEscape(envFields.MessageID), fetchFormat) + data, err := rt.CallAPI(ctx, "GET", path, nil) + if err != nil { + return nil, fmt.Errorf("fetch mail message %s: %w", envFields.MessageID, err) + } + + var fetched struct { + Data struct { + From string `json:"from"` + Subject string `json:"subject"` + Snippet string `json:"snippet"` + FolderID string `json:"folder_id"` + LabelIDs []string `json:"label_ids"` + BodyText string `json:"body_text"` + BodyHTML string `json:"body_html"` + Attachments []MailAttachment `json:"attachments"` + } `json:"data"` + } + if err := json.Unmarshal(data, &fetched); err != nil { + return nil, fmt.Errorf("decode fetched mail %s: %w", envFields.MessageID, err) + } + + // Filter: folders + if len(folders) > 0 && !contains(folders, fetched.Data.FolderID) { + return nil, nil + } + // Filter: labels (event must have ALL of the requested labels) + if len(labels) > 0 && !allIn(fetched.Data.LabelIDs, labels) { + return nil, nil + } + + // Enrich payload based on msg-format + if msgFormat == "metadata" || msgFormat == "plain_text_full" || msgFormat == "full" { + payload.From = fetched.Data.From + payload.Subject = fetched.Data.Subject + payload.Snippet = fetched.Data.Snippet + payload.FolderID = fetched.Data.FolderID + payload.LabelIDs = fetched.Data.LabelIDs + } + if msgFormat == "plain_text_full" || msgFormat == "full" { + payload.BodyText = fetched.Data.BodyText + } + if msgFormat == "full" { + payload.BodyHTML = fetched.Data.BodyHTML + payload.Attachments = fetched.Data.Attachments + } + + return json.Marshal(payload) +} + +type eventEnvelopeFields struct { + MessageID string + MailAddress string + MailboxType int + Subscriber string +} + +func extractEventFields(rawPayload json.RawMessage) (eventEnvelopeFields, error) { + var env struct { + Event struct { + MessageID string `json:"message_id"` + MailAddress string `json:"mail_address"` + MailboxType int `json:"mailbox_type"` + Subscriber string `json:"subscriber"` + } `json:"event"` + } + if err := json.Unmarshal(rawPayload, &env); err != nil { + return eventEnvelopeFields{}, err + } + return eventEnvelopeFields{ + MessageID: env.Event.MessageID, + MailAddress: env.Event.MailAddress, + MailboxType: env.Event.MailboxType, + Subscriber: env.Event.Subscriber, + }, nil +} + +func splitCSV(s string) []string { + if s == "" { + return nil + } + parts := strings.Split(s, ",") + out := make([]string, 0, len(parts)) + for _, p := range parts { + p = strings.TrimSpace(p) + if p != "" { + out = append(out, p) + } + } + return out +} + +func contains(haystack []string, needle string) bool { + for _, h := range haystack { + if h == needle { + return true + } + } + return false +} + +func allIn(haystack, needles []string) bool { + for _, n := range needles { + if !contains(haystack, n) { + return false + } + } + return true +} diff --git a/events/mail/process_test.go b/events/mail/process_test.go new file mode 100644 index 000000000..820654ef3 --- /dev/null +++ b/events/mail/process_test.go @@ -0,0 +1,247 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "context" + "encoding/json" + "errors" + "strings" + "testing" + + "github.com/larksuite/cli/internal/event" +) + +// processFakeRT lets us stub message metadata fetch. +type processFakeRT struct { + messages map[string]json.RawMessage + pathsCalled []string +} + +func (f *processFakeRT) CallAPI(ctx context.Context, method, path string, body interface{}) (json.RawMessage, error) { + f.pathsCalled = append(f.pathsCalled, method+" "+path) + if msg, ok := f.messages[path]; ok { + return msg, nil + } + return json.RawMessage(`{}`), nil +} + +type fetchErrorRT struct { + err error +} + +func (f *fetchErrorRT) CallAPI(ctx context.Context, method, path string, body interface{}) (json.RawMessage, error) { + return nil, f.err +} + +func makeMailEvent(mailAddr, messageID string) *event.RawEvent { + return &event.RawEvent{ + EventType: "mail.user_mailbox.event.message_received_v1", + Payload: json.RawMessage(`{"schema":"2.0","header":{},"event":{"mail_address":"` + mailAddr + `","message_id":"` + messageID + `","mailbox_type":1,"subscriber":"ou_xxx"}}`), + } +} + +func TestProcessMailEvent_EventFormat_NoFetch(t *testing.T) { + rt := &processFakeRT{} + params := map[string]string{"mailbox": "alice@example.com", "msg-format": "event"} + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out == nil { + t.Fatal("event format should not drop the message") + } + if len(rt.pathsCalled) != 0 { + t.Errorf("event format must not call API; called: %v", rt.pathsCalled) + } + var parsed MailReceivedPayload + if err := json.Unmarshal(out, &parsed); err != nil { + t.Fatal(err) + } + if parsed.MessageID != "msg_1" || parsed.MailAddress != "alice@example.com" { + t.Errorf("missing event fields: %+v", parsed) + } + if parsed.Subject != "" { + t.Errorf("event format must not have subject: %+v", parsed) + } +} + +func TestProcessMailEvent_MetadataFormat_FetchesMessage(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=metadata": json.RawMessage(`{"data":{"from":"sender@x.com","subject":"hello","snippet":"hi there","folder_id":"INBOX","label_ids":["FLAGGED"]}}`), + }, + } + params := map[string]string{"mailbox": "alice@example.com", "msg-format": "metadata"} + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out == nil { + t.Fatal("metadata format should not drop") + } + var parsed MailReceivedPayload + json.Unmarshal(out, &parsed) + if parsed.Subject != "hello" || parsed.From != "sender@x.com" || parsed.FolderID != "INBOX" { + t.Errorf("metadata fields not populated: %+v", parsed) + } +} + +func TestProcessMailEvent_FoldersFilter_Drops(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=metadata": json.RawMessage(`{"data":{"folder_id":"TRASH","subject":"x"}}`), + }, + } + params := map[string]string{ + "mailbox": "alice@example.com", + "folders": "INBOX", + "msg-format": "metadata", + } + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out != nil { + t.Errorf("event in TRASH but filter=INBOX should drop; got %s", string(out)) + } +} + +func TestProcessMailEvent_LabelsFilter_Drops(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=metadata": json.RawMessage(`{"data":{"label_ids":["UNREAD"],"subject":"x"}}`), + }, + } + params := map[string]string{ + "mailbox": "alice@example.com", + "labels": "FLAGGED", + "msg-format": "metadata", + } + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out != nil { + t.Errorf("event without FLAGGED label should drop; got %s", string(out)) + } +} + +func TestProcessMailEvent_FullFormat_IncludesBodyHTML(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=full": json.RawMessage(`{"data":{"subject":"x","body_text":"text","body_html":"

html

","attachments":[{"attachment_id":"a1","filename":"f.pdf","size_bytes":100,"content_type":"application/pdf"}]}}`), + }, + } + params := map[string]string{"mailbox": "alice@example.com", "msg-format": "full"} + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + var parsed MailReceivedPayload + json.Unmarshal(out, &parsed) + if parsed.BodyHTML != "

html

" { + t.Errorf("missing body_html in full format: %+v", parsed) + } + if len(parsed.Attachments) != 1 || parsed.Attachments[0].Filename != "f.pdf" { + t.Errorf("missing attachments: %+v", parsed) + } +} + +func TestProcessMailEvent_PlainTextFullFormat_FetchesPlainText(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=plain_text_full": json.RawMessage(`{"data":{"subject":"hello","body_text":"plain body","body_html":"

html

"}}`), + }, + } + params := map[string]string{"mailbox": "alice@example.com", "msg-format": "plain_text_full"} + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out == nil { + t.Fatal("plain_text_full should not drop") + } + var parsed MailReceivedPayload + json.Unmarshal(out, &parsed) + if parsed.BodyText != "plain body" { + t.Errorf("body_text not populated: %+v", parsed) + } + if parsed.BodyHTML != "" { + t.Errorf("body_html should NOT be present at plain_text_full: %+v", parsed) + } + if parsed.Subject != "hello" { + t.Errorf("subject (metadata field) should be populated: %+v", parsed) + } +} + +func TestProcessMailEvent_MissingMailboxError(t *testing.T) { + rt := &processFakeRT{} + params := map[string]string{"msg-format": "metadata"} // no mailbox + _, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err == nil { + t.Fatal("expected error when mailbox missing and fetch needed") + } + if !strings.Contains(err.Error(), "mailbox param required") { + t.Errorf("error message wrong: %v", err) + } +} + +func TestProcessMailEvent_FetchAPIError_Wraps(t *testing.T) { + rt := &fetchErrorRT{err: errors.New("network down")} + params := map[string]string{"mailbox": "alice@example.com", "msg-format": "metadata"} + _, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err == nil { + t.Fatal("expected wrapped fetch error") + } + if !strings.Contains(err.Error(), "fetch mail message msg_1") { + t.Errorf("missing wrap context: %v", err) + } + if !strings.Contains(err.Error(), "network down") { + t.Errorf("underlying error not propagated: %v", err) + } +} + +func TestProcessMailEvent_FoldersFilter_Passes(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=metadata": json.RawMessage(`{"data":{"folder_id":"INBOX","subject":"x"}}`), + }, + } + params := map[string]string{ + "mailbox": "alice@example.com", + "folders": "INBOX,SENT", // multi-folder filter (OR semantics) + "msg-format": "metadata", + } + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out == nil { + t.Errorf("event in INBOX should pass filter=INBOX,SENT (OR)") + } +} + +func TestProcessMailEvent_LabelsFilter_PassesAllPresent(t *testing.T) { + rt := &processFakeRT{ + messages: map[string]json.RawMessage{ + "/open-apis/mail/v1/user_mailboxes/alice@example.com/messages/msg_1?format=metadata": json.RawMessage(`{"data":{"label_ids":["FLAGGED","IMPORTANT"],"subject":"x"}}`), + }, + } + params := map[string]string{ + "mailbox": "alice@example.com", + "labels": "FLAGGED,IMPORTANT", // both required (AND) + "msg-format": "metadata", + } + out, err := processMailEvent(context.Background(), rt, makeMailEvent("alice@example.com", "msg_1"), params) + if err != nil { + t.Fatal(err) + } + if out == nil { + t.Errorf("event with both FLAGGED+IMPORTANT should pass") + } +} + +// Compile-time: processMailEvent must match the Process signature. +var _ func(context.Context, event.APIClient, *event.RawEvent, map[string]string) (json.RawMessage, error) = processMailEvent From 08e90f77c260c3c041b1383980a647bcfd3c6e47 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:48:55 +0800 Subject: [PATCH 17/24] feat(events/mail): wire folders/labels/msg-format params + new framework hooks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds events/mail/register.go with Keys() exposing the mail.user_mailbox.event.message_received_v1 EventKey: mailbox (SUB-KEY), folders, labels, msg-format params; wires NormalizeParams, PreConsume (subscribe/unsubscribe), Match, and Process hooks. Updates events/register.go to include mail.Keys() alongside im.Keys(). Note: Schema.Custom is used (not Native) because processMailEvent produces the complete output shape — Schema.Native is incompatible with Process per registry validation. Change-Id: Ibf48dc19dee5db65730810b0f2e4b5ebed73c4f0 --- events/mail/register.go | 114 +++++++++++++++++++++++++++++++++++ events/mail/register_test.go | 97 +++++++++++++++++++++++++++++ events/register.go | 3 +- 3 files changed, 213 insertions(+), 1 deletion(-) create mode 100644 events/mail/register.go create mode 100644 events/mail/register_test.go diff --git a/events/mail/register.go b/events/mail/register.go new file mode 100644 index 000000000..7dbc475df --- /dev/null +++ b/events/mail/register.go @@ -0,0 +1,114 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "context" + "fmt" + "net/url" + "reflect" + "strings" + "time" + + "github.com/larksuite/cli/internal/event" +) + +const ( + mailMessageReceivedKey = "mail.user_mailbox.event.message_received_v1" + mailSubscribeEventTypeNewMessage = 1 +) + +// Keys returns all Mail-domain EventKey definitions. +func Keys() []event.KeyDefinition { + return []event.KeyDefinition{ + { + Key: mailMessageReceivedKey, + DisplayName: "New mail received", + Description: "Triggered when a new email arrives in the user's mailbox.", + EventType: mailMessageReceivedKey, + // Schema.Custom is required here (not Native) because processMailEvent + // produces the complete MailReceivedPayload shape. Schema.Native is + // incompatible with Process per registry validation. + Schema: event.SchemaDef{ + Custom: &event.SchemaSpec{Type: reflect.TypeOf(MailReceivedPayload{})}, + }, + Params: []event.ParamDef{ + { + Name: "mailbox", + Type: event.ParamString, + Default: "me", + SubscriptionKey: true, + Description: "Mailbox to subscribe to (email address or 'me'). Determines subscription identity — different mailboxes get independent server-side subscriptions and event streams.", + }, + { + Name: "folders", + Type: event.ParamString, + Description: "Filter: comma-separated folder IDs. Drop events whose mail is not in any of these folders. Triggers a metadata fetch per event.", + }, + { + Name: "labels", + Type: event.ParamString, + Description: "Filter: comma-separated label IDs. Drop events whose mail does not carry ALL of these labels.", + }, + { + Name: "msg-format", + Type: event.ParamEnum, + Default: "event", + Values: []event.ParamValue{ + {Value: "event", Desc: "Raw event payload only (no API call). Fields: message_id, mail_address, mailbox_type, subscriber."}, + {Value: "metadata", Desc: "event fields + from, subject, snippet, folder_id, label_ids (1 GET per event)."}, + {Value: "plain_text_full", Desc: "metadata + body_text (1 GET per event with format=plain_text_full)."}, + {Value: "full", Desc: "metadata + body_text + body_html + attachments (1 GET per event with format=full)."}, + }, + Description: "Output enrichment level. See Output Schema field descriptions for which fields are populated at each level.", + }, + }, + Scopes: []string{ + "mail:event", + "mail:user_mailbox.event.mail_address:read", + "mail:user_mailbox:readonly", + "mail:user_mailbox.message:readonly", + }, + AuthTypes: []string{"user"}, + RequiredConsoleEvents: []string{mailMessageReceivedKey}, + NormalizeParams: normalizeMailParams, + PreConsume: preConsumeMailSubscribe, + Match: matchMailbox, + Process: processMailEvent, + }, + } +} + +// preConsumeMailSubscribe opens the per-user mailbox event subscription before +// the consumer starts receiving events, and returns a cleanup that unsubscribes +// on graceful shutdown. The subscribe/unsubscribe APIs are idempotent on the +// server side keyed by (app, user, event_type). +func preConsumeMailSubscribe(ctx context.Context, rt event.APIClient, params map[string]string) (func() error, error) { + mailbox := strings.TrimSpace(params["mailbox"]) + if mailbox == "" { + mailbox = "me" + } + body := map[string]interface{}{"event_type": mailSubscribeEventTypeNewMessage} + if _, err := rt.CallAPI(ctx, "POST", mailboxEventPath(mailbox, "subscribe"), body); err != nil { + return nil, fmt.Errorf("subscribe mailbox events failed for %q: %w", mailbox, err) + } + cleanup := func() error { + // Fresh context: the parent ctx is already cancelled when cleanup runs, + // but unsubscribe must still reach the server. Budget is small (10s) + // to keep graceful shutdown snappy on flaky networks. + cleanupCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + if _, err := rt.CallAPI(cleanupCtx, "POST", mailboxEventPath(mailbox, "unsubscribe"), body); err != nil { + return fmt.Errorf("unsubscribe mailbox=%s: %w", mailbox, err) + } + return nil + } + return cleanup, nil +} + +// mailboxEventPath builds /open-apis/mail/v1/user_mailboxes//event/ +// with each path segment URL-escaped to handle email addresses containing reserved chars. +func mailboxEventPath(mailbox, action string) string { + return "/open-apis/mail/v1/user_mailboxes/" + url.PathEscape(mailbox) + "/event/" + url.PathEscape(action) +} diff --git a/events/mail/register_test.go b/events/mail/register_test.go new file mode 100644 index 000000000..25049620a --- /dev/null +++ b/events/mail/register_test.go @@ -0,0 +1,97 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT + +package mail + +import ( + "testing" +) + +func TestRegister_HasOneEventKey(t *testing.T) { + keys := Keys() + if len(keys) != 1 { + t.Fatalf("expected 1 EventKey, got %d", len(keys)) + } +} + +func TestRegister_HasSubscriptionKeyMailbox(t *testing.T) { + k := Keys()[0] + var foundSubKey bool + for _, p := range k.Params { + if p.Name == "mailbox" && p.SubscriptionKey { + foundSubKey = true + } + } + if !foundSubKey { + t.Error("mailbox param should be marked SubscriptionKey=true") + } +} + +func TestRegister_HasNormalizeMatchProcess(t *testing.T) { + k := Keys()[0] + if k.NormalizeParams == nil { + t.Error("NormalizeParams hook should be set") + } + if k.Match == nil { + t.Error("Match hook should be set") + } + if k.Process == nil { + t.Error("Process hook should be set") + } + if k.PreConsume == nil { + t.Error("PreConsume hook should be set") + } +} + +func TestRegister_HasAllParams(t *testing.T) { + k := Keys()[0] + wantNames := []string{"mailbox", "folders", "labels", "msg-format"} + gotNames := make(map[string]bool) + for _, p := range k.Params { + gotNames[p.Name] = true + } + for _, n := range wantNames { + if !gotNames[n] { + t.Errorf("missing param: %s", n) + } + } +} + +// TestRegister_SchemaIsCustomMailReceivedPayload verifies Schema.Custom is used +// (not Native) because processMailEvent produces the complete output shape. +// Schema.Native is incompatible with Process per registry validation. +func TestRegister_SchemaIsCustomMailReceivedPayload(t *testing.T) { + k := Keys()[0] + if k.Schema.Custom == nil || k.Schema.Custom.Type == nil { + t.Fatal("Schema should be Custom with non-nil Type") + } + if k.Schema.Custom.Type.Name() != "MailReceivedPayload" { + t.Errorf("schema type is %v, want MailReceivedPayload", k.Schema.Custom.Type) + } +} + +func TestRegister_AuthTypesUserOnly(t *testing.T) { + k := Keys()[0] + if len(k.AuthTypes) != 1 || k.AuthTypes[0] != "user" { + t.Errorf("AuthTypes = %v, want [user]", k.AuthTypes) + } +} + +func TestRegister_RequiredScopes(t *testing.T) { + k := Keys()[0] + want := map[string]bool{ + "mail:event": true, + "mail:user_mailbox.event.mail_address:read": true, + "mail:user_mailbox:readonly": true, + "mail:user_mailbox.message:readonly": true, + } + got := make(map[string]bool) + for _, s := range k.Scopes { + got[s] = true + } + for s := range want { + if !got[s] { + t.Errorf("missing scope: %s", s) + } + } +} diff --git a/events/register.go b/events/register.go index e570da623..d3b9c63fd 100644 --- a/events/register.go +++ b/events/register.go @@ -6,15 +6,16 @@ package events import ( "github.com/larksuite/cli/events/im" + "github.com/larksuite/cli/events/mail" "github.com/larksuite/cli/events/minutes" "github.com/larksuite/cli/events/vc" "github.com/larksuite/cli/internal/event" ) -// Mail is intentionally omitted in this phase. func init() { all := [][]event.KeyDefinition{ im.Keys(), + mail.Keys(), minutes.Keys(), vc.Keys(), } From becaac09a74d61ceb20a546e533bf628750c8c92 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 11:51:28 +0800 Subject: [PATCH 18/24] docs(skills): document subscription identity + cleanup error semantics Change-Id: I14636cae6a459cdf5a82455bc18022d5edd6c5ce --- skills/lark-event/SKILL.md | 21 +++++++++++++++++++ .../lark-mail/references/lark-mail-watch.md | 13 ++++++++++++ 2 files changed, 34 insertions(+) diff --git a/skills/lark-event/SKILL.md b/skills/lark-event/SKILL.md index 2c816ba64..09ad6a4df 100644 --- a/skills/lark-event/SKILL.md +++ b/skills/lark-event/SKILL.md @@ -138,6 +138,27 @@ Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common val **Aside**: `--param`'s valid parameters also live in the schema — the `params` section lists `name` / `type` / `required` / `enum` / `default` / `description`; **section missing = this key accepts no `--param`**. +## Per-EventKey subscription identity + +Some EventKeys subscribe at the **resource** level rather than app-globally — e.g. `mail.user_mailbox.event.message_received_v1` subscribes per-mailbox. For these, the framework distinguishes consumers by `(EventKey, params marked SubscriptionKey)`: + +- Two `event consume mail.xxx` processes with different `-p mailbox=...` open **independent** server-side subscriptions and receive **independent** event streams. +- `event schema ` shows a `SUB-KEY` column flagging which params participate in subscription identity. +- `event status` shows a `SUB` column distinguishing co-existing subscriptions. + +Concrete: `lark-cli event consume mail.user_mailbox.event.message_received_v1 -p mailbox=alice@x.com` and `... -p mailbox=bob@x.com` against the same `lark-cli` profile produce two distinct subscription scopes; each gets its own subscribe/unsubscribe lifecycle. + +For EventKeys without any `SUB-KEY` param (e.g. all IM EventKeys), every `event consume` of that EventKey shares one subscription scope — today's behavior. + +## Cleanup error reporting + +When the consumer exits gracefully and is the last for its subscription scope, the framework runs the cleanup (unsubscribe) callback. Two stderr outcomes: + +- Success: `[event] cleanup done.` +- Failure: `WARN: cleanup failed: (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)` + +**Important**: do NOT manually call unsubscribe APIs as a recovery action. Subscriptions are reference-counted implicitly by Lark's server (one record per `(app, user, event_type)`), so a stray unsubscribe will silently affect other co-living consumers. The WARN is informational; the next consumer's subscribe call self-heals. + ## Topic index | Topic | Reference | Coverage | diff --git a/skills/lark-mail/references/lark-mail-watch.md b/skills/lark-mail/references/lark-mail-watch.md index 43c5fd8d8..99e037a12 100644 --- a/skills/lark-mail/references/lark-mail-watch.md +++ b/skills/lark-mail/references/lark-mail-watch.md @@ -92,3 +92,16 @@ lark-cli mail +watch --print-output-schema - [lark-mail](../SKILL.md) — 邮箱域总览 - [lark-mail-triage](lark-mail-triage.md) — 邮件摘要列表 - [lark-event-subscribe](../../lark-event/references/lark-event-subscribe.md) — 通用事件订阅 + +## When to prefer `event consume mail.xxx` vs `mail +watch` + +Both paths receive the same upstream events (share the server-side subscription record). Choose based on agent needs: + +| Need | Use | +|------|-----| +| Unified entry across IM + mail + future domains | `lark-cli event consume mail.user_mailbox.event.message_received_v1` | +| Multiple mailboxes from one agent session | `event consume` (each `-p mailbox=...` gets independent stream) | +| Pinned to `mail +watch` workflows in older scripts | `mail +watch` (no behavior change) | +| Need `--output-dir` writing per-message JSON files | `mail +watch` (this flag stays on `+watch` for now) | + +Both paths support `-p msg-format=event|metadata|plain_text_full|full` and folder/label filtering via `-p folders=…,-p labels=...`. Field coverage is identical. From 31c57a63e6b3f7784dc1b48b4350437d824162b1 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Mon, 25 May 2026 21:47:13 +0800 Subject: [PATCH 19/24] fix(events/mail): use /user_mailboxes/me/profile with primary_email_address Change-Id: I03d0780aaac0fd7d59c1395df6912f5bb043f996 --- events/mail/normalize.go | 43 ++++++++++++++++++++++++----------- events/mail/normalize_test.go | 8 +++---- 2 files changed, 34 insertions(+), 17 deletions(-) diff --git a/events/mail/normalize.go b/events/mail/normalize.go index 9ab0cf67b..5e80288de 100644 --- a/events/mail/normalize.go +++ b/events/mail/normalize.go @@ -16,29 +16,46 @@ import ( // user's real primary email so fingerprint / Match / Process all see the // canonical value. // -// API: GET /open-apis/mail/v1/user_mailboxes/me — returns {data:{email:"..."}} -// Verified via: lark-cli api GET /open-apis/mail/v1/user_mailboxes/me --as user +// API: GET /open-apis/mail/v1/user_mailboxes/me/profile — returns +// {data:{primary_email_address:"..."}}. Mirrors the same OAPI call that +// shortcuts/mail/helpers.go::fetchMailboxPrimaryEmail uses, so both code +// paths (event consume and mail +watch) resolve "me" identically. func normalizeMailParams(ctx context.Context, rt event.APIClient, params map[string]string) error { mbox := strings.TrimSpace(params["mailbox"]) if mbox == "" || mbox == "me" { - data, err := rt.CallAPI(ctx, "GET", "/open-apis/mail/v1/user_mailboxes/me", nil) + data, err := rt.CallAPI(ctx, "GET", "/open-apis/mail/v1/user_mailboxes/me/profile", nil) if err != nil { return fmt.Errorf("resolve mailbox 'me': %w", err) } - var parsed struct { - Data struct { - Email string `json:"email"` - } `json:"data"` - } - if err := json.Unmarshal(data, &parsed); err != nil { - return fmt.Errorf("decode user_mailboxes/me response: %w", err) + email, err := extractPrimaryEmail(data) + if err != nil { + return fmt.Errorf("decode user_mailboxes/me/profile response: %w", err) } - if parsed.Data.Email == "" { - return fmt.Errorf("user_mailboxes/me returned empty email") + if email == "" { + return fmt.Errorf("user_mailboxes/me/profile returned empty primary_email_address") } - params["mailbox"] = parsed.Data.Email + params["mailbox"] = email return nil } params["mailbox"] = mbox return nil } + +// extractPrimaryEmail pulls primary_email_address out of the profile response. +// Tolerates both top-level shape (test fixtures) and the canonical nested +// `data` wrapper used by production responses. +func extractPrimaryEmail(raw json.RawMessage) (string, error) { + var asTop struct { + PrimaryEmailAddress string `json:"primary_email_address"` + Data struct { + PrimaryEmailAddress string `json:"primary_email_address"` + } `json:"data"` + } + if err := json.Unmarshal(raw, &asTop); err != nil { + return "", err + } + if asTop.PrimaryEmailAddress != "" { + return asTop.PrimaryEmailAddress, nil + } + return asTop.Data.PrimaryEmailAddress, nil +} diff --git a/events/mail/normalize_test.go b/events/mail/normalize_test.go index 68fc58439..5c855dc61 100644 --- a/events/mail/normalize_test.go +++ b/events/mail/normalize_test.go @@ -40,14 +40,14 @@ func TestNormalizeMailParams(t *testing.T) { { name: "me resolves to real email", input: "me", - response: json.RawMessage(`{"data":{"email":"liuxinyang@example.com"}}`), + response: json.RawMessage(`{"data":{"primary_email_address":"liuxinyang@example.com"}}`), wantOut: "liuxinyang@example.com", wantAPICall: true, }, { name: "empty resolves to real email", input: "", - response: json.RawMessage(`{"data":{"email":"liuxinyang@example.com"}}`), + response: json.RawMessage(`{"data":{"primary_email_address":"liuxinyang@example.com"}}`), wantOut: "liuxinyang@example.com", wantAPICall: true, }, @@ -72,8 +72,8 @@ func TestNormalizeMailParams(t *testing.T) { { name: "empty email in response is error", input: "me", - response: json.RawMessage(`{"data":{"email":""}}`), - wantErrSub: "empty email", + response: json.RawMessage(`{"data":{"primary_email_address":""}}`), + wantErrSub: "empty primary_email_address", }, } for _, tt := range tests { From c2741c591a1becb978ff77042b648a3350321e82 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Tue, 26 May 2026 11:39:09 +0800 Subject: [PATCH 20/24] docs(skills): converge mail event docs into lark-event (IM-style) Change-Id: If46580dff10e15a56858157dbcdfb79f2c43d227 --- skills/lark-event/SKILL.md | 5 +- .../lark-event/references/lark-event-mail.md | 122 ++++++++++++++++++ skills/lark-mail/SKILL.md | 3 +- .../lark-mail/references/lark-mail-triage.md | 2 +- .../lark-mail/references/lark-mail-watch.md | 107 --------------- 5 files changed, 128 insertions(+), 111 deletions(-) create mode 100644 skills/lark-event/references/lark-event-mail.md delete mode 100644 skills/lark-mail/references/lark-mail-watch.md diff --git a/skills/lark-event/SKILL.md b/skills/lark-event/SKILL.md index 09ad6a4df..11f70731f 100644 --- a/skills/lark-event/SKILL.md +++ b/skills/lark-event/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-event version: 1.0.0 -description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume ` (covers IM messages/reactions/chat changes, VC meeting ended, Minutes generated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses." +description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume ` (covers IM message receive, reactions, chat member changes, VC meeting ended, Minutes generated, mail new-message arrival, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses." metadata: requires: bins: ["lark-cli"] @@ -53,6 +53,8 @@ lark-cli event consume im.message.receive_v1 --as bot > receive.ndjson lark-cli event consume im.message.reaction.created_v1 --as bot > reaction.ndjson & wait +# Mail: subscribe to new-message arrival for the current user (--as user required) +lark-cli event consume mail.user_mailbox.event.message_received_v1 -p mailbox=me --as user ``` ## Call flow @@ -166,3 +168,4 @@ When the consumer exits gracefully and is the last for its subscription scope, t | IM | [`references/lark-event-im.md`](references/lark-event-im.md) | Catalog of 11 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender) | | VC | [`references/lark-event-vc.md`](references/lark-event-vc.md) | Catalog of 2 VC EventKeys (`vc.meeting.participant_meeting_ended_v1`, `vc.note.generated_v1`) + field reference + source type semantics (meeting only) | | Minutes | [`references/lark-event-minutes.md`](references/lark-event-minutes.md) | Catalog of 1 Minutes EventKey (`minutes.minute.generated_v1`) + field reference + source type semantics (meeting only) | +| Mail | [`references/lark-event-mail.md`](references/lark-event-mail.md) | `mail.user_mailbox.event.message_received_v1` EventKey + per-mailbox subscription identity (`-p mailbox=...`) + msg-format levels (event / metadata / plain_text_full / full) + folders/labels filters + cleanup semantics. | diff --git a/skills/lark-event/references/lark-event-mail.md b/skills/lark-event/references/lark-event-mail.md new file mode 100644 index 000000000..f6eb0d3e9 --- /dev/null +++ b/skills/lark-event/references/lark-event-mail.md @@ -0,0 +1,122 @@ +# Mail Events + +> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage). + +## Key catalog (1) + +| EventKey | Purpose | +|---|---| +| `mail.user_mailbox.event.message_received_v1` | New email arrived in a user mailbox | + +**Identity:** `--as user` only. Bot identity is rejected at param-validation time. The current user must have console event `mail.user_mailbox.event.message_received_v1` subscribed in the developer console (and the app must be published) before `event consume` will run. + +## Params + +| Name | Role | Default | Description | +|---|---|---|---| +| `mailbox` | subscription identity | `me` | Email address (or `me` for the current user). Different mailboxes get **independent** server-side subscriptions; running two `event consume` processes with different `-p mailbox=...` is supported and each gets its own subscribe/cleanup lifecycle. | +| `folders` | filter | — | Comma-separated folder IDs. Events whose mail is not in any of these folders are dropped (triggers one metadata fetch per event). | +| `labels` | filter | — | Comma-separated label IDs. Events whose mail does **not carry all** of these labels are dropped (AND semantics). | +| `msg-format` | output enrichment | `event` | Controls which fields are populated. See output schema below. | + +`event` schema shows `SUB-KEY=yes` on `mailbox` (the only subscription identity param). The other three are filter / process params; changing their values does **not** open a new subscription. + +## Output schema (union, by `msg-format`) + +The output struct is a union — fields populate progressively as `msg-format` increases. Fields absent at a lower level are omitted from JSON (omitempty). + +| Field | event | metadata | plain_text_full | full | +|---|:-:|:-:|:-:|:-:| +| `message_id` | ✅ | ✅ | ✅ | ✅ | +| `mail_address` | ✅ | ✅ | ✅ | ✅ | +| `mailbox_type` | ✅ | ✅ | ✅ | ✅ | +| `subscriber` | ✅ | ✅ | ✅ | ✅ | +| `from` | — | ✅ | ✅ | ✅ | +| `subject` | — | ✅ | ✅ | ✅ | +| `snippet` | — | ✅ | ✅ | ✅ | +| `folder_id` | — | ✅ | ✅ | ✅ | +| `label_ids` | — | ✅ | ✅ | ✅ | +| `body_text` | — | — | ✅ | ✅ | +| `body_html` | — | — | — | ✅ | +| `attachments` | — | — | — | ✅ | + +**Picking a level**: +- `event` (default): no per-event API call. Use when you only need `message_id` to fetch on demand via `mail +message`. +- `metadata`: 1 GET per event. Use for triage / notification — gives subject + from + snippet. +- `plain_text_full`: 1 GET per event with `format=plain_text`. Use when you need the body for content analysis but don't care about HTML/attachments. +- `full`: 1 GET per event with `format=full`. Use when you need attachments metadata or the HTML body. + +Run `lark-cli event schema mail.user_mailbox.event.message_received_v1` for the live field reference (descriptions per field include the conditional, e.g. `"Sender email address (msg-format >= metadata)"`). + +## Pipeline: receive then fetch on demand + +For long-running agents, default to `msg-format=event` and fetch only when needed. Cheaper, lower latency, and the message API gives you everything `msg-format=full` would. + +```bash +lark-cli event consume mail.user_mailbox.event.message_received_v1 --as user \ + --jq '{id: .message_id, addr: .mail_address}' \ +| while IFS= read -r evt; do + msg_id=$(echo "$evt" | jq -r '.id') + lark-cli mail +message --message-id "$msg_id" --as user + done +``` + +## Multi-mailbox + +Each `-p mailbox=...` value (after normalize) yields a distinct `SubscriptionID`. The bus daemon dedups PreConsume/cleanup per `SubscriptionID`, so the following two processes run **independent** subscriptions and event streams against the same Feishu app: + +```bash +# Terminal A +lark-cli event consume mail.user_mailbox.event.message_received_v1 \ + -p mailbox=alice@x.com --as user + +# Terminal B +lark-cli event consume mail.user_mailbox.event.message_received_v1 \ + -p mailbox=bob@x.com --as user +``` + +`event status` shows both as separate rows under a single EventKey, distinguished by the `SUB` column (the fingerprint suffix). + +## `me` alias resolution + +`-p mailbox=me` (the default) is resolved to the current user's real primary email at startup via `GET /open-apis/mail/v1/user_mailboxes/me/profile`. After resolution, the real email is what flows through fingerprint / PreConsume / Match / Process. So `me` and the explicit email of the same user produce the same `SubscriptionID` (no accidental duplicate subscriptions). + +If your user has no mailbox provisioned (e.g. enterprise email not yet enabled), this call returns an error and `event consume` exits with a `normalize params for ...: resolve mailbox 'me': ...` message. + +## Filter recipes + +### 1. New mail to a specific folder only + +```bash +lark-cli event consume mail.user_mailbox.event.message_received_v1 \ + -p mailbox=me -p folders=INBOX -p msg-format=metadata --as user \ + --jq '{from, subject, snippet}' +``` + +### 2. Flagged (starred) mail across all folders + +```bash +lark-cli event consume mail.user_mailbox.event.message_received_v1 \ + -p mailbox=me -p labels=FLAGGED -p msg-format=metadata --as user +``` + +Use `lark-cli mail labels list` to discover label IDs. + +### 3. Drop mail from a specific sender + +`folders` / `labels` are positive filters; for sender exclusion use `--jq`: + +```bash +lark-cli event consume mail.user_mailbox.event.message_received_v1 \ + -p mailbox=me -p msg-format=metadata --as user \ + --jq 'select(.from != "noreply@example.com")' +``` + +## Cleanup + +On graceful exit (`--max-events`/`--timeout` reached, or SIGTERM/stdin EOF), the last consumer for a `SubscriptionID` runs cleanup: a POST to `unsubscribe`. Two stderr outcomes: + +- Success: `[event] cleanup done.` +- Failure: `WARN: cleanup failed: (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)` + +The Feishu server-side subscribe record is `(app, user, event_type)`-keyed and idempotent, so a failed unsubscribe leaks at most one stale record per `(app, user)` until the next `event consume` for that key — which silently overwrites it. Agents **MUST NOT** manually call the unsubscribe API as a recovery action: the server has no reference counting, so a stray unsubscribe will silently kill another co-living consumer's stream. diff --git a/skills/lark-mail/SKILL.md b/skills/lark-mail/SKILL.md index e045c6e27..af37c4ffe 100644 --- a/skills/lark-mail/SKILL.md +++ b/skills/lark-mail/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-mail version: 1.0.0 -description: "飞书邮箱 — draft, compose, send, reply, forward, read, and search emails; manage drafts, folders, labels, contacts, attachments, and mail rules. Use when user mentions 起草邮件, 写一封邮件, 拟邮件, 草稿, 发通知邮件, 发送邮件, 发邮件, 回复邮件, 转发邮件, 查看邮件, 看邮件, 读邮件, 搜索邮件, 查邮件, 收件箱, 邮件会话, 编辑草稿, 管理草稿, 下载附件, 邮件文件夹, 邮件标签, 邮件联系人, 监听新邮件, 收信规则, 邮件规则, draft, compose, send email, reply, forward, inbox, mail thread, mail rules." +description: "飞书邮箱 — draft, compose, send, reply, forward, read, and search emails; manage drafts, folders, labels, contacts, attachments, and mail rules. Use when user mentions 起草邮件, 写一封邮件, 拟邮件, 草稿, 发通知邮件, 发送邮件, 发邮件, 回复邮件, 转发邮件, 查看邮件, 看邮件, 读邮件, 搜索邮件, 查邮件, 收件箱, 邮件会话, 编辑草稿, 管理草稿, 下载附件, 邮件文件夹, 邮件标签, 邮件联系人, 收信规则, 邮件规则, draft, compose, send email, reply, forward, inbox, mail thread, mail rules." metadata: requires: bins: ["lark-cli"] @@ -470,7 +470,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli mail + [flags]`） | [`+messages`](references/lark-mail-messages.md) | Use when reading full content for multiple emails by message ID. Prefer this shortcut over calling raw mail user_mailbox.messages batch_get directly, because it base64url-decodes body fields and returns normalized per-message output that is easier to consume. | | [`+thread`](references/lark-mail-thread.md) | Use when querying a full mail conversation/thread by thread ID. Returns all messages in chronological order, including replies and drafts, with body content and attachments metadata, including inline images. | | [`+triage`](references/lark-mail-triage.md) | List mail summaries (date/from/subject/message_id). Use --query for full-text search, --filter for exact-match conditions. | -| [`+watch`](references/lark-mail-watch.md) | Watch for incoming mail events via WebSocket (requires scope mail:event and bot event mail.user_mailbox.event.message_received_v1 added). Run with --print-output-schema to see per-format field reference before parsing output. | | [`+reply`](references/lark-mail-reply.md) | Reply to a message and save as draft (default). Use --confirm-send to send immediately after user confirmation. Sets Re: subject, In-Reply-To, and References headers automatically. | | [`+reply-all`](references/lark-mail-reply-all.md) | Reply to all recipients and save as draft (default). Use --confirm-send to send immediately after user confirmation. Includes all original To and CC automatically. | | [`+send`](references/lark-mail-send.md) | Compose a new email and save as draft (default). Use --confirm-send to send immediately after user confirmation. | diff --git a/skills/lark-mail/references/lark-mail-triage.md b/skills/lark-mail/references/lark-mail-triage.md index f427e1f1e..e9fac3ee9 100644 --- a/skills/lark-mail/references/lark-mail-triage.md +++ b/skills/lark-mail/references/lark-mail-triage.md @@ -119,4 +119,4 @@ tip: use mail +message --message-id to read full content ## 参考 - [lark-mail](../SKILL.md) — 邮箱域总览 -- [lark-mail-watch](lark-mail-watch.md) — 实时监听新邮件 +- [lark-event](../../lark-event/SKILL.md) — 实时监听新邮件（`event consume mail.user_mailbox.event.message_received_v1`） diff --git a/skills/lark-mail/references/lark-mail-watch.md b/skills/lark-mail/references/lark-mail-watch.md deleted file mode 100644 index 99e037a12..000000000 --- a/skills/lark-mail/references/lark-mail-watch.md +++ /dev/null @@ -1,107 +0,0 @@ - -# mail +watch - -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 - -实时监听新邮件事件（`mail.user_mailbox.event.message_received_v1`）。 - -**权限要求：** 应用需要 `mail:event`、`mail:user_mailbox.message:readonly` 权限，以及字段权限 `mail:user_mailbox.message.address:read`、`mail:user_mailbox.message.subject:read`、`mail:user_mailbox.message.body:read`，且机器人需订阅事件 `mail.user_mailbox.event.message_received_v1`。按需权限（缺失时会提示申请）：使用 `--folders` / `--folder-ids` 筛选自定义文件夹时需要 `mail:user_mailbox.folder:read`；使用 `--labels` / `--label-ids` 筛选自定义标签时需要 `mail:user_mailbox.message:modify`。 - -## 命令 - -```bash -# 默认：表格输出 message 元数据 -lark-cli mail +watch - -# 仅输出 message 数据（jq 友好） -lark-cli mail +watch --msg-format metadata --format data - -# 输出精简元数据（message_id / thread_id / folder_id / label_ids / internal_date / message_state） -lark-cli mail +watch --msg-format minimal --format data - -# 输出纯文本全文 -lark-cli mail +watch --msg-format plain_text_full --format data - -# 输出完整 message（含正文相关字段） -lark-cli mail +watch --msg-format full --format data - -# 输出原始事件体 -lark-cli mail +watch --msg-format event --format data - -# 监听指定邮箱 -lark-cli mail +watch --mailbox alice@company.com - -# 按文件夹/标签过滤（客户端过滤，支持名称或 ID） -lark-cli mail +watch --folders '["收件箱项目"]' --label-ids '["FLAGGED"]' - -# 写入文件 -lark-cli mail +watch --msg-format metadata --output-dir ./mail-events - -# 查看各 --msg-format 的输出字段说明（解析前先运行） -lark-cli mail +watch --print-output-schema -``` - -## 参数 - -| 参数 | 默认 | 说明 | -|------|------|------| -| `--mailbox ` | `me` | 订阅目标邮箱 | -| `--msg-format ` | `metadata` | 输出模式：`metadata` / `minimal` / `plain_text_full` / `full` / `event` | -| `--format ` | `table` | 输出样式：`table` / `json` / `data` | -| `--folder-ids ` | — | 文件夹 ID 过滤，如 `["INBOX","SENT"]` | -| `--folders ` | — | 文件夹名称过滤（与 `--folder-ids` 取并集） | -| `--label-ids ` | — | 标签 ID 过滤，如 `["FLAGGED","IMPORTANT"]` | -| `--labels ` | — | 标签名称过滤（与 `--label-ids` 取并集） | - -> **过滤逻辑：** `--folder-ids`/`--folders` 与 `--label-ids`/`--labels` 之间是 **AND** 关系，即邮件必须**同时**匹配指定的文件夹和标签才会输出。同类参数内部是 **OR** 关系（匹配其中任一即可）。新收到的邮件通常只有系统标签（如 `UNREAD`、`IMPORTANT`），不会自动带有自定义标签。 -| `--output-dir ` | — | 每条事件写入单独 JSON 文件 | -| `--print-output-schema` | — | 打印各 `--msg-format` 的输出字段说明（解析输出前先运行此命令） | -| `--dry-run` | — | 仅预览订阅请求，不实际连接 | - -## --msg-format 输出结构（--format json） - -每条事件输出为一行 NDJSON。 - -**`metadata`**（默认，适合分拣/通知） -```json -{"ok":true,"data":{"message":{"message_id":"...","thread_id":"...","subject":"...","head_from":{"name":"Alice","mail_address":"alice@example.com"},"to":[{"name":"Bob","mail_address":"bob@example.com"}],"folder_id":"INBOX","label_ids":["IMPORTANT"],"internal_date":"1742800000000","message_state":1,"body_preview":"Please find attached..."}}} -``` - -**`minimal`**（仅 ID 和状态，适合追踪已读/文件夹变更） -```json -{"ok":true,"data":{"message":{"message_id":"...","thread_id":"...","folder_id":"INBOX","label_ids":["IMPORTANT"],"internal_date":"1742800000000","message_state":1}}} -``` - -**`plain_text_full`**（metadata 全部字段 + 完整纯文本正文） -```json -{"ok":true,"data":{"message":{"message_id":"...","subject":"...","head_from":{...},"folder_id":"INBOX","label_ids":[...],"body_preview":"...","body_plain_text":""}}} -``` - -**`event`**（原始 WebSocket 事件，不发起 API 请求，适合调试） -```json -{"ok":true,"data":{"header":{"event_id":"abc123","event_type":"mail.user_mailbox.event.message_received_v1","create_time":"1742800000000"},"event":{"message_id":"...","mail_address":"user@example.com"}}} -``` - -**`full`**（全部字段，含 HTML 正文和附件） -```json -{"ok":true,"data":{"message":{"message_id":"...","subject":"...","head_from":{...},"body_preview":"...","body_plain_text":"","body_html":"","attachments":[{"name":"report.pdf","size":102400}]}}} -``` - -## 参考 - -- [lark-mail](../SKILL.md) — 邮箱域总览 -- [lark-mail-triage](lark-mail-triage.md) — 邮件摘要列表 -- [lark-event-subscribe](../../lark-event/references/lark-event-subscribe.md) — 通用事件订阅 - -## When to prefer `event consume mail.xxx` vs `mail +watch` - -Both paths receive the same upstream events (share the server-side subscription record). Choose based on agent needs: - -| Need | Use | -|------|-----| -| Unified entry across IM + mail + future domains | `lark-cli event consume mail.user_mailbox.event.message_received_v1` | -| Multiple mailboxes from one agent session | `event consume` (each `-p mailbox=...` gets independent stream) | -| Pinned to `mail +watch` workflows in older scripts | `mail +watch` (no behavior change) | -| Need `--output-dir` writing per-message JSON files | `mail +watch` (this flag stays on `+watch` for now) | - -Both paths support `-p msg-format=event|metadata|plain_text_full|full` and folder/label filtering via `-p folders=…,-p labels=...`. Field coverage is identical. From cbbc84c425d59a493e05039dcbac4c9e6c69c3b5 Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 30 May 2026 12:46:22 +0800 Subject: [PATCH 21/24] fix(events/mail): decode subscriber as structured user_ids object The mail message_received event's subscriber field is a {user_ids:[{user_id,open_id,union_id}]} object per the Feishu SDK (P2UserMailboxEventMessageReceivedV1Data.Subscriber), not a string. Decoding it as string made Process fail at runtime with 'cannot unmarshal object into Go struct field .event.subscriber of type string', silently dropping every mail event. Change-Id: I91dcd7e82659e3962a2530fae8d5ee34fe40dbf6 --- events/mail/payload.go | 22 +++++++++++++++---- events/mail/process.go | 10 ++++----- events/mail/process_test.go | 2 +- .../lark-event/references/lark-event-mail.md | 2 +- 4 files changed, 25 insertions(+), 11 deletions(-) diff --git a/events/mail/payload.go b/events/mail/payload.go index c9efb50c5..26308ab3f 100644 --- a/events/mail/payload.go +++ b/events/mail/payload.go @@ -15,10 +15,10 @@ package mail // - msg-format=full : metadata + BodyText + BodyHTML + Attachments type MailReceivedPayload struct { // Always present (msg-format=event and above) - MessageID string `json:"message_id" desc:"Unique message identifier"` - MailAddress string `json:"mail_address" desc:"Recipient mailbox address (matches the subscribed mailbox)"` - MailboxType int `json:"mailbox_type" desc:"Mailbox type enum: 1=primary, 2=shared"` - Subscriber string `json:"subscriber" desc:"open_id of the user who owns the subscription"` + MessageID string `json:"message_id" desc:"Unique message identifier"` + MailAddress string `json:"mail_address" desc:"Recipient mailbox address (matches the subscribed mailbox)"` + MailboxType int `json:"mailbox_type" desc:"Mailbox type enum: 1=primary, 2=shared"` + Subscriber Subscriber `json:"subscriber" desc:"Subscribers of the event — the users whose mailbox received this message"` // Populated when msg-format >= metadata From string `json:"from,omitempty" desc:"Sender email address (msg-format >= metadata)"` @@ -41,3 +41,17 @@ type MailAttachment struct { SizeBytes int64 `json:"size_bytes" desc:"Size in bytes"` ContentType string `json:"content_type" desc:"MIME type"` } + +// Subscriber is the raw event-envelope `subscriber` block: the set of users +// whose mailbox received the message. Each element carries the three Feishu +// user identifier forms (user_id, open_id, union_id); fields are omitempty +// because in practice only the IDs the app is scoped to are populated. +type Subscriber struct { + UserIDs []SubscriberUserID `json:"user_ids,omitempty" desc:"Recipients of the mail event (mailbox owners)"` +} + +type SubscriberUserID struct { + UserID string `json:"user_id,omitempty" desc:"Tenant-scoped user_id"` + OpenID string `json:"open_id,omitempty" desc:"App-scoped open_id"` + UnionID string `json:"union_id,omitempty" desc:"Cross-tenant union_id"` +} diff --git a/events/mail/process.go b/events/mail/process.go index 37e39fb71..65bb8671a 100644 --- a/events/mail/process.go +++ b/events/mail/process.go @@ -111,16 +111,16 @@ type eventEnvelopeFields struct { MessageID string MailAddress string MailboxType int - Subscriber string + Subscriber Subscriber } func extractEventFields(rawPayload json.RawMessage) (eventEnvelopeFields, error) { var env struct { Event struct { - MessageID string `json:"message_id"` - MailAddress string `json:"mail_address"` - MailboxType int `json:"mailbox_type"` - Subscriber string `json:"subscriber"` + MessageID string `json:"message_id"` + MailAddress string `json:"mail_address"` + MailboxType int `json:"mailbox_type"` + Subscriber Subscriber `json:"subscriber"` } `json:"event"` } if err := json.Unmarshal(rawPayload, &env); err != nil { diff --git a/events/mail/process_test.go b/events/mail/process_test.go index 820654ef3..e5e7e9d36 100644 --- a/events/mail/process_test.go +++ b/events/mail/process_test.go @@ -38,7 +38,7 @@ func (f *fetchErrorRT) CallAPI(ctx context.Context, method, path string, body in func makeMailEvent(mailAddr, messageID string) *event.RawEvent { return &event.RawEvent{ EventType: "mail.user_mailbox.event.message_received_v1", - Payload: json.RawMessage(`{"schema":"2.0","header":{},"event":{"mail_address":"` + mailAddr + `","message_id":"` + messageID + `","mailbox_type":1,"subscriber":"ou_xxx"}}`), + Payload: json.RawMessage(`{"schema":"2.0","header":{},"event":{"mail_address":"` + mailAddr + `","message_id":"` + messageID + `","mailbox_type":1,"subscriber":{"user_ids":[{"open_id":"ou_xxx"}]}}}`), } } diff --git a/skills/lark-event/references/lark-event-mail.md b/skills/lark-event/references/lark-event-mail.md index f6eb0d3e9..9ba0fe21f 100644 --- a/skills/lark-event/references/lark-event-mail.md +++ b/skills/lark-event/references/lark-event-mail.md @@ -30,7 +30,7 @@ The output struct is a union — fields populate progressively as `msg-format` i | `message_id` | ✅ | ✅ | ✅ | ✅ | | `mail_address` | ✅ | ✅ | ✅ | ✅ | | `mailbox_type` | ✅ | ✅ | ✅ | ✅ | -| `subscriber` | ✅ | ✅ | ✅ | ✅ | +| `subscriber.user_ids[].{user_id,open_id,union_id}` | ✅ | ✅ | ✅ | ✅ | | `from` | — | ✅ | ✅ | ✅ | | `subject` | — | ✅ | ✅ | ✅ | | `snippet` | — | ✅ | ✅ | ✅ | From 95f5b80e22df25e5e72213d7a39188df46b655ed Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 30 May 2026 16:02:50 +0800 Subject: [PATCH 22/24] fix(events): adapt minutes/vc PreConsume cleanup to func() error The PreConsume cleanup signature changed from func() to func() error in this branch. minutes and vc (added on main since this branch forked) share a subscriptionPreConsume helper that returned the old signature; update both to return the unsubscribe error so the framework can surface cleanup failures uniformly. Change-Id: I808a4446e8b9327d4e6ec20e2b28a48345b5e1b9 --- events/minutes/preconsume.go | 11 +++++++---- events/vc/preconsume.go | 11 +++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/events/minutes/preconsume.go b/events/minutes/preconsume.go index 82c329c85..3a3302a02 100644 --- a/events/minutes/preconsume.go +++ b/events/minutes/preconsume.go @@ -13,8 +13,8 @@ import ( const cleanupTimeout = 5 * time.Second -func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) { - return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) { +func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func() error, error) { + return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func() error, error) { if rt == nil { return nil, fmt.Errorf("runtime API client is required for pre-consume subscription") } @@ -24,10 +24,13 @@ func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) fu return nil, err } - return func() { + return func() error { cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout) defer cancel() - _, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body) + if _, err := rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body); err != nil { + return fmt.Errorf("unsubscribe %s: %w", eventType, err) + } + return nil }, nil } } diff --git a/events/vc/preconsume.go b/events/vc/preconsume.go index 9bd03d941..abd093750 100644 --- a/events/vc/preconsume.go +++ b/events/vc/preconsume.go @@ -13,8 +13,8 @@ import ( const cleanupTimeout = 5 * time.Second -func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) { - return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) { +func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func() error, error) { + return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func() error, error) { if rt == nil { return nil, fmt.Errorf("runtime API client is required for pre-consume subscription") } @@ -24,10 +24,13 @@ func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) fu return nil, err } - return func() { + return func() error { cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout) defer cancel() - _, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body) + if _, err := rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body); err != nil { + return fmt.Errorf("unsubscribe %s: %w", eventType, err) + } + return nil }, nil } } From a42f7346219fc246aa828a2445233b42b678960b Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 30 May 2026 16:15:35 +0800 Subject: [PATCH 23/24] chore: gofmt event test files Change-Id: I9cd51022a644db509a070234fcc330783a4d08cc --- events/mail/process_test.go | 2 +- events/mail/register_test.go | 2 +- internal/event/bus/hub_test.go | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/events/mail/process_test.go b/events/mail/process_test.go index e5e7e9d36..b8e720465 100644 --- a/events/mail/process_test.go +++ b/events/mail/process_test.go @@ -38,7 +38,7 @@ func (f *fetchErrorRT) CallAPI(ctx context.Context, method, path string, body in func makeMailEvent(mailAddr, messageID string) *event.RawEvent { return &event.RawEvent{ EventType: "mail.user_mailbox.event.message_received_v1", - Payload: json.RawMessage(`{"schema":"2.0","header":{},"event":{"mail_address":"` + mailAddr + `","message_id":"` + messageID + `","mailbox_type":1,"subscriber":{"user_ids":[{"open_id":"ou_xxx"}]}}}`), + Payload: json.RawMessage(`{"schema":"2.0","header":{},"event":{"mail_address":"` + mailAddr + `","message_id":"` + messageID + `","mailbox_type":1,"subscriber":{"user_ids":[{"open_id":"ou_xxx"}]}}}`), } } diff --git a/events/mail/register_test.go b/events/mail/register_test.go index 25049620a..1753df3c9 100644 --- a/events/mail/register_test.go +++ b/events/mail/register_test.go @@ -80,7 +80,7 @@ func TestRegister_AuthTypesUserOnly(t *testing.T) { func TestRegister_RequiredScopes(t *testing.T) { k := Keys()[0] want := map[string]bool{ - "mail:event": true, + "mail:event": true, "mail:user_mailbox.event.mail_address:read": true, "mail:user_mailbox:readonly": true, "mail:user_mailbox.message:readonly": true, diff --git a/internal/event/bus/hub_test.go b/internal/event/bus/hub_test.go index 6de5ff539..04fe53641 100644 --- a/internal/event/bus/hub_test.go +++ b/internal/event/bus/hub_test.go @@ -239,8 +239,8 @@ func newTestConn(eventKey string, eventTypes []string) *testConn { func (c *testConn) EventKey() string { return c.eventKey } // SubscriptionID falls back to EventKey for test mocks that don't set a separate subscription ID. -func (c *testConn) SubscriptionID() string { return c.eventKey } -func (c *testConn) EventTypes() []string { return c.eventTypes } +func (c *testConn) SubscriptionID() string { return c.eventKey } +func (c *testConn) EventTypes() []string { return c.eventTypes } func (c *testConn) SendCh() chan interface{} { return c.sendCh } func (c *testConn) PID() int { return c.pid } func (c *testConn) IncrementReceived() { c.received.Add(1) } From 654f65640ffce2918e9f1d0f144201f581cbfd8d Mon Sep 17 00:00:00 2001 From: "liuxinyang.lxy" Date: Sat, 30 May 2026 16:24:52 +0800 Subject: [PATCH 24/24] fix(events): address CodeRabbit review on PR - match.go: fail open when mail_address is absent/empty (shape drift), not only on unparseable payload - conn.go: PreShutdownCheck uses the connection's own SubscriptionID() instead of recomputing from the (possibly stale) incoming message - consume_test: drive the real Run() path for the normalize-error wrap; drop the self-fulfilling cleanup-format test (covered by sandbox E2E) - loop_test: record real call order instead of bare call counts - lark-event SKILL.md: correct server semantics (idempotent single record, not reference counting) Change-Id: I62319e84a990e5355a462280f190fd397a8a6c2d --- events/mail/match.go | 12 ++++-- internal/event/bus/conn.go | 12 +++--- internal/event/consume/consume_test.go | 60 +++++++++++++------------- internal/event/consume/loop_test.go | 13 +++--- skills/lark-event/SKILL.md | 2 +- 5 files changed, 54 insertions(+), 45 deletions(-) diff --git a/events/mail/match.go b/events/mail/match.go index 38368a60a..83df5f3a9 100644 --- a/events/mail/match.go +++ b/events/mail/match.go @@ -12,9 +12,10 @@ import ( // matchMailbox compares the V2-envelope payload's event.mail_address against // the normalized params.mailbox. Drops events whose mail_address doesn't match. // -// Fail-open policy: if params.mailbox is empty (no filter), or payload can't -// be parsed (defensive — upstream schema may evolve), accept the event rather -// than silently dropping legitimate traffic. +// Fail-open policy: if params.mailbox is empty (no filter), the payload can't +// be parsed, or the payload omits/moves event.mail_address (defensive — +// upstream schema may evolve), accept the event rather than silently dropping +// legitimate traffic. Only a present-but-mismatched mail_address drops. // // IMPORTANT: caller must ensure params.mailbox is already normalized to a real // email (not "me"). normalizeMailParams handles this. @@ -29,7 +30,10 @@ func matchMailbox(raw *event.RawEvent, params map[string]string) bool { } `json:"event"` } if err := json.Unmarshal(raw.Payload, &env); err != nil { - return true // fail-open + return true // fail-open on unparseable payload + } + if env.Event.MailAddress == "" { + return true // fail-open on shape drift (field absent/moved); let Process decide } return env.Event.MailAddress == target } diff --git a/internal/event/bus/conn.go b/internal/event/bus/conn.go index 76b2c5d2b..f0af67b54 100644 --- a/internal/event/bus/conn.go +++ b/internal/event/bus/conn.go @@ -143,14 +143,16 @@ func (c *Conn) ReaderLoop() { } func (c *Conn) handleControlMessage(msg interface{}) { - switch m := msg.(type) { + switch msg.(type) { case *protocol.Bye: c.shutdown() case *protocol.PreShutdownCheck: - scope := m.SubscriptionID - if scope == "" { - scope = m.EventKey - } + // Use the connection's own authoritative subscription identity rather + // than recomputing from the incoming message: a stale or mismatched + // PreShutdownCheck must not ask about the wrong scope (which would + // suppress or mistrigger per-subscription cleanup). Conn.SubscriptionID() + // already falls back to EventKey when its stored subID is empty. + scope := c.SubscriptionID() lastForKey := true if c.checkLastForKey != nil { lastForKey = c.checkLastForKey(scope) diff --git a/internal/event/consume/consume_test.go b/internal/event/consume/consume_test.go index 9f11e644c..2dce2ecb5 100644 --- a/internal/event/consume/consume_test.go +++ b/internal/event/consume/consume_test.go @@ -3,10 +3,13 @@ package consume -// NOTE: Run() requires bus daemon + transport infrastructure. Testing the full -// Run path end-to-end is complex. For this task we test the parts: -// (a) NormalizeParams error wrapping -// (b) doHello correctly threads subscriptionID through to the Hello message. +// NOTE: TestNormalizeParams_ErrorIsWrappedWithEventKey drives the real Run() +// path — NormalizeParams fails before EnsureBus, so no bus/transport is +// actually exercised, yet the assertion covers the production error-wrapping +// code (not a reconstruction). TestDoHello_PassesSubscriptionIDToWire covers +// the Hello wire encoding. The cleanup-error WARN format is verified +// end-to-end by the sandbox E2E (TestEventConsume_Mail_ReadyAndTimeout), +// which asserts the real stderr contract rather than a duplicated literal. import ( "bufio" @@ -14,13 +17,13 @@ import ( "context" "encoding/json" "errors" - "fmt" "net" "strings" "testing" "github.com/larksuite/cli/internal/event" "github.com/larksuite/cli/internal/event/protocol" + "github.com/larksuite/cli/internal/event/transport" ) // fakeRT is a minimal event.APIClient mock. @@ -33,24 +36,35 @@ func (f *fakeRT) CallAPI(_ context.Context, _, _ string, _ interface{}) (json.Ra } func TestNormalizeParams_ErrorIsWrappedWithEventKey(t *testing.T) { - // We test the error wrapping pattern in isolation: same call site Run uses. - keyDef := &event.KeyDefinition{ - Key: "test.evt_normalize_fail", + // Drive the real Run() path. NormalizeParams failure returns before + // EnsureBus, so the bus/transport is never actually contacted, but the + // error-wrapping under test (`fmt.Errorf("normalize params for %s: %w")`) + // is the genuine production code path — if Run() ever stops wrapping, this + // test fails. + const key = "test.evt_normalize_fail" + event.RegisterKey(event.KeyDefinition{ + Key: key, + EventType: key, + Schema: event.SchemaDef{Custom: &event.SchemaSpec{Raw: json.RawMessage(`{"type":"object"}`)}}, NormalizeParams: func(_ context.Context, _ event.APIClient, _ map[string]string) error { return errors.New("simulated normalize failure") }, - } - err := keyDef.NormalizeParams(context.Background(), &fakeRT{}, map[string]string{}) + }) + defer event.UnregisterKeyForTest(key) + + err := Run(context.Background(), transport.New(), "app", "", "", Options{ + EventKey: key, + Runtime: &fakeRT{}, + Quiet: true, + }) if err == nil { - t.Fatal("expected error from NormalizeParams") + t.Fatal("expected Run to fail when NormalizeParams errors") } - // Run wraps with: fmt.Errorf("normalize params for %s: %w", EventKey, err) - wrapped := fmt.Errorf("normalize params for %s: %w", keyDef.Key, err) - if !strings.Contains(wrapped.Error(), "normalize params for test.evt_normalize_fail:") { - t.Errorf("wrap format wrong: %v", wrapped) + if !strings.Contains(err.Error(), "normalize params for "+key+":") { + t.Errorf("error not wrapped with EventKey prefix: %v", err) } - if !strings.Contains(wrapped.Error(), "simulated normalize failure") { - t.Errorf("underlying error not propagated: %v", wrapped) + if !strings.Contains(err.Error(), "simulated normalize failure") { + t.Errorf("underlying error not propagated: %v", err) } } @@ -95,15 +109,3 @@ func TestDoHello_PassesSubscriptionIDToWire(t *testing.T) { t.Errorf("Hello.SubscriptionID on wire = %q, want %q", got, "mail.x:alice") } } - -func TestCleanupErrorBranching_Format(t *testing.T) { - // Unit-level check of the message format. We don't run full Run() — too - // much wiring. Instead we verify the format string is correct by checking - // the literal we expect in stderr matches what the spec mandates. - want := "WARN: cleanup failed: simulated unsubscribe failure (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)" - got := fmt.Sprintf("WARN: cleanup failed: %v (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)", - errors.New("simulated unsubscribe failure")) - if got != want { - t.Errorf("format mismatch:\n got: %s\nwant: %s", got, want) - } -} diff --git a/internal/event/consume/loop_test.go b/internal/event/consume/loop_test.go index 9ce6270e4..ace554fd7 100644 --- a/internal/event/consume/loop_test.go +++ b/internal/event/consume/loop_test.go @@ -257,16 +257,17 @@ func TestProcessAndOutput_Match_NilAcceptsAll(t *testing.T) { } func TestProcessAndOutput_Match_RunsBeforeProcess(t *testing.T) { - processCalls := 0 - matchCalls := 0 + // Record the actual call sequence — a bare call-count check would still + // pass if Process ran before Match. + var order []string keyDef := &event.KeyDefinition{ Key: "test.evt", Match: func(raw *event.RawEvent, params map[string]string) bool { - matchCalls++ + order = append(order, "match") return true }, Process: func(ctx context.Context, rt event.APIClient, raw *event.RawEvent, params map[string]string) (json.RawMessage, error) { - processCalls++ + order = append(order, "process") return raw.Payload, nil }, } @@ -280,8 +281,8 @@ func TestProcessAndOutput_Match_RunsBeforeProcess(t *testing.T) { if !wrote { t.Error("expected wrote=true") } - if matchCalls != 1 || processCalls != 1 { - t.Errorf("match=%d process=%d, want 1/1", matchCalls, processCalls) + if len(order) != 2 || order[0] != "match" || order[1] != "process" { + t.Errorf("call order = %v, want [match process]", order) } } diff --git a/skills/lark-event/SKILL.md b/skills/lark-event/SKILL.md index 11f70731f..32772d7ad 100644 --- a/skills/lark-event/SKILL.md +++ b/skills/lark-event/SKILL.md @@ -159,7 +159,7 @@ When the consumer exits gracefully and is the last for its subscription scope, t - Success: `[event] cleanup done.` - Failure: `WARN: cleanup failed: (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)` -**Important**: do NOT manually call unsubscribe APIs as a recovery action. Subscriptions are reference-counted implicitly by Lark's server (one record per `(app, user, event_type)`), so a stray unsubscribe will silently affect other co-living consumers. The WARN is informational; the next consumer's subscribe call self-heals. +**Important**: do NOT manually call unsubscribe APIs as a recovery action. Lark's server keeps a single idempotent record per `(app, user, event_type)` — subscribe overwrites it, and there is no reference counting — so a stray unsubscribe deletes that one record and silently cuts off every co-living consumer sharing it. The WARN is informational; the next consumer's subscribe call self-heals. ## Topic index