Kubernetes Dependency Watches Development Guide

You are an expert in the stolostron/kubernetes-dependency-watches library, an event-driven Go library for tracking dependencies between Kubernetes objects.

Project Overview

This is an event-driven Go library for tracking dependencies between Kubernetes objects. When a Kubernetes object needs to monitor changes to other objects (e.g., a ConfigMap watching a Secret), this library provides an efficient watch mechanism with optional caching. It is designed as an alternative/complement to controller-runtime and can be integrated with controller-runtime as a Channel Source.

Core Architecture

Main Components

**DynamicWatcher** (`client/client.go`): The central interface and implementation

- `watchedToWatchers`: maps watched objects to watchers that care about them

- `watcherToWatches`: maps watcher objects to the objects they watch

- `watches`: maps watched objects to their active API watch requests

**ObjectCache** (`client/cache.go`): Thread-safe caching layer

**ControllerRuntimeSource** (`client/source.go`): Integration adapter

Key Concepts

**ObjectIdentifier**: Identifies a Kubernetes object or set of objects

**Watch Lifecycle**:

1. `AddWatcher` or `AddOrUpdateWatcher` creates watches

2. `relayWatchEvents` runs in goroutines, monitoring watch channels

3. On watch events, watchers get added to the reconcile queue

4. Watch automatically restarts if it fails (e.g., resource version expired)

5. `RemoveWatcher` cleans up watches when no longer referenced

**Query Batch Pattern**: For caching use cases

1. `StartQueryBatch` begins a transaction

2. `Get`/`List` calls add watches and return cached objects

3. `EndQueryBatch` removes watches no longer referenced in the batch

Development Instructions

When working with this codebase:

1. **Testing**:

- Run all tests: `make test`

- Run with coverage: `make test-coverage`

- Custom test args: `TESTARGS="-v -ginkgo.focus='My Test'" make test`

- Tests use Ginkgo/Gomega with envtest for a real Kubernetes API server

- `ENVTEST_K8S_VERSION` is auto-determined from go.mod (k8s.io/api version)

- See `client_example_test.go` for comprehensive usage examples

2. **Code Quality**:

- Run linters: `make lint`

- Format code: `make fmt`

- Security scan: `make gosec-scan`

3. **Dependencies**:

- Install test dependencies: `make e2e-dependencies`

- Install envtest: `make envtest`

Important Implementation Details

**Watch Restart Behavior** (`client.go:309-422`):

**Concurrency Safety**:

**Error Handling**:

Integration Patterns

**Standalone Usage**:

```go

dynamicWatcher, _ := client.New(k8sConfig, reconciler, nil)

go dynamicWatcher.Start(ctx)

<-dynamicWatcher.Started()

dynamicWatcher.AddWatcher(watcher, watched)

```

**Controller-Runtime Integration**:

```go

reconciler, sourceChan := client.NewControllerRuntimeSource()

dynamicWatcher, _ := client.New(k8sConfig, reconciler, nil)

go dynamicWatcher.Start(ctx)

ctrl.NewControllerManagedBy(mgr).

For(&MyType{}).

WatchesRawSource(sourceChan).

Complete(myReconciler)

```

Key Files Reference

Constraints