Initial implementation

Author: devflex-pro

.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+      - uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.12.2
+      - run: go test ./...
+      - run: go test -race ./...
+      - run: go test -run='^$' -bench=. -benchtime=100ms ./...

.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.idea/
+.vscode/
+*.test
+coverage.out
+dist/

.golangci.yml

@@ -0,0 +1,33 @@
+version: "2"
+run:
+  modules-download-mode: readonly
+  tests: true
+linters:
+  default: none
+  enable:
+    - errcheck
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+formatters:
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$

API.md

@@ -0,0 +1,81 @@
+# Public API
+
+```go
+package chanprobe
+
+var (
+    ErrClosed error
+    ErrFull   error
+)
+
+type DropPolicy int
+
+const (
+    Block DropPolicy = iota
+    DropNewest
+    DropOldest
+)
+
+type Option func(*Options)
+
+type Options struct {
+    DropPolicy DropPolicy
+    Registry   *Registry
+}
+
+func WithDropPolicy(policy DropPolicy) Option
+func WithRegistry(reg *Registry) Option
+
+type Queue[T any] struct{}
+
+func New[T any](name string, capacity int, opts ...Option) *Queue[T]
+
+func (q *Queue[T]) Name() string
+func (q *Queue[T]) Send(ctx context.Context, item T) error
+func (q *Queue[T]) Recv(ctx context.Context) (T, bool)
+func (q *Queue[T]) TrySend(item T) bool
+func (q *Queue[T]) TryRecv() (T, bool)
+func (q *Queue[T]) Close()
+func (q *Queue[T]) Len() int
+func (q *Queue[T]) Cap() int
+func (q *Queue[T]) Snapshot() Snapshot
+
+type Snapshot struct {
+    Name             string        `json:"name"`
+    Len              int           `json:"len"`
+    Cap              int           `json:"cap"`
+    Closed           bool          `json:"closed"`
+    SentTotal        uint64        `json:"sent_total"`
+    ReceivedTotal    uint64        `json:"received_total"`
+    DroppedTotal     uint64        `json:"dropped_total"`
+    SendBlockedTotal uint64        `json:"send_blocked_total"`
+    RecvBlockedTotal uint64        `json:"recv_blocked_total"`
+    SendWaitTotal    time.Duration `json:"send_wait_total"`
+    RecvWaitTotal    time.Duration `json:"recv_wait_total"`
+    ItemWaitTotal    time.Duration `json:"item_wait_total"`
+    OldestItemAge    time.Duration `json:"oldest_item_age"`
+}
+
+type Snapshoter interface {
+    Snapshot() Snapshot
+}
+
+type Registry struct{}
+
+func NewRegistry() *Registry
+func DefaultRegistry() *Registry
+func (r *Registry) Register(name string, snapper Snapshoter)
+func (r *Registry) Unregister(name string)
+func (r *Registry) Snapshots() []Snapshot
+
+func PublishExpvar(name string, reg *Registry)
+```
+
+## Notes
+
+- `New` panics for an empty name or non-positive capacity.
+- `Send` returns `ErrClosed` after `Close`.
+- `Send` returns `ctx.Err()` when a blocking send is canceled.
+- `Recv` returns `ok=false` when the queue is closed and drained, or when a
+  blocking receive is canceled.
+- `PublishExpvar` uses `DefaultRegistry()` when the registry argument is nil.

BENCHMARKS.md

@@ -0,0 +1,61 @@
+# Benchmark plan
+
+Benchmarks should be honest and not overclaim.
+
+Run:
+
+```bash
+go test -bench=. -benchmem ./...
+```
+
+For more stable local numbers, run multiple samples:
+
+```bash
+go test -run='^$' -bench=. -benchmem -count=5 ./...
+```
+
+## Benchmark cases
+
+1. Plain channel send/recv same goroutine.
+2. `chanprobe.Queue` Send/Recv same goroutine.
+3. Plain channel producer/consumer.
+4. `chanprobe.Queue` producer/consumer.
+5. TrySend/TryRecv.
+6. Snapshot under load.
+
+## Interpreting results
+
+Compare related pairs:
+
+- `BenchmarkChannelSameGoroutine` vs `BenchmarkQueueSameGoroutine`
+- `BenchmarkChannelProducerConsumer` vs `BenchmarkQueueProducerConsumer`
+
+Native channels are the baseline. `chanprobe.Queue` is expected to cost more
+because it tracks counters, wait durations, item age, close state, and supports
+context-aware blocking operations.
+
+`BenchmarkQueueTrySendTryRecv` measures the non-blocking fast path.
+
+`BenchmarkQueueSnapshot` measures the cost of reading observability data from a
+populated queue.
+
+Example local result on an AMD Ryzen 3 4300U:
+
+```text
+BenchmarkChannelSameGoroutine-4       30.80 ns/op    0 B/op  0 allocs/op
+BenchmarkQueueSameGoroutine-4       2293 ns/op       0 B/op  0 allocs/op
+BenchmarkChannelProducerConsumer-4    51.11 ns/op    0 B/op  0 allocs/op
+BenchmarkQueueProducerConsumer-4    2389 ns/op       0 B/op  0 allocs/op
+BenchmarkQueueTrySendTryRecv-4      2262 ns/op       0 B/op  0 allocs/op
+BenchmarkQueueSnapshot-4            1164 ns/op       0 B/op  0 allocs/op
+```
+
+Treat these as local reference numbers, not a universal performance claim.
+
+## README benchmark wording
+
+Do not claim `chanprobe` is faster than channels.
+
+Expected positioning:
+
+> `chanprobe` adds observability and context-aware queue operations. It has overhead compared to native channels. Use it at important async boundaries where visibility matters.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevFlex Pro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

METRICS.md

@@ -0,0 +1,73 @@
+# Metrics design
+
+## Core principle
+
+The core package exposes snapshots. Exporters convert snapshots to external systems.
+
+This avoids forcing dependencies on users.
+
+## Snapshot fields
+
+### Len and Cap
+
+Current queue occupancy.
+
+Useful to detect saturation but not enough alone.
+
+### SentTotal and ReceivedTotal
+
+Basic throughput counters.
+
+### DroppedTotal
+
+Critical for lossy queues.
+
+Increment when:
+
+- `DropNewest` rejects incoming work.
+- `DropOldest` evicts old work.
+
+### SendBlockedTotal
+
+Increment when a `Send` call found a full queue and had to wait under `Block`.
+
+### RecvBlockedTotal
+
+Increment when a `Recv` call found an empty queue and had to wait.
+
+### SendWaitTotal and RecvWaitTotal
+
+Total accumulated waiting time.
+
+Average wait can be derived as:
+
+```text
+avg_send_wait = SendWaitTotal / SendBlockedTotal
+avg_recv_wait = RecvWaitTotal / RecvBlockedTotal
+```
+
+### ItemWaitTotal
+
+Total time items spent inside the queue before being received.
+
+Average queue age can be derived as:
+
+```text
+avg_item_wait = ItemWaitTotal / ReceivedTotal
+```
+
+### OldestItemAge
+
+Age of the oldest item currently in the queue.
+
+This is one of the most useful incident metrics.
+
+## v1 deliberately avoids histograms
+
+Histograms require either:
+
+- a dependency on a metrics backend,
+- a custom approximate histogram implementation,
+- or more API surface.
+
+For v1, snapshots are enough. Prometheus/OpenTelemetry adapters can add histograms later.