feat: game lobby service

lobby/internal/ports/streamlagprobe.go

@@ -0,0 +1,20 @@
+package ports
+
+import (
+	"context"
+	"time"
+)
+
+// StreamLagProbe reports how far the persisted consumer offset trails the
+// stream tail. It feeds the three `lobby.*.oldest_unprocessed_age_ms`
+// observable gauges defined in `lobby/README.md` §Observability.
+type StreamLagProbe interface {
+	// OldestUnprocessedAge returns the age of the first stream entry that
+	// follows savedOffset on stream. The boolean return reports whether
+	// the implementation could compute an age at all: it is false when
+	// the stream is empty, when no entries follow savedOffset, or when
+	// the stream key is absent. An empty savedOffset is interpreted as
+	// "no progress yet"; the implementation falls back to the stream
+	// head in that case.
+	OldestUnprocessedAge(ctx context.Context, stream, savedOffset string) (time.Duration, bool, error)
+}