feat: add NewClient constructor with functional options

Also updates the (fake pkg) readme to be more concise

Author: ecordell

client/fake/README.md

@@ -1,259 +1,149 @@
 # Fake Dynamic Client
 
-This package provides enhanced fake dynamic clients for testing Kubernetes controllers with Custom Resource Definitions (CRDs).
+Enhanced fake dynamic client for testing Kubernetes controllers with Custom Resource Definitions (CRDs).
 
 ## Features
 
-- **CRD Support**: Automatic registration of CRD types with proper schema validation
-- **Multi-Version CRDs**: Full support for CRDs with multiple API versions
-- **Server-Side Apply**: Proper field management and strategic merge patch support
-- **Embedded CRDs**: Load CRDs from embedded byte data using `go:embed`
-- **OpenAPI Integration**: Custom OpenAPI spec support for different Kubernetes versions
+- **Server-Side Apply**: Full field management and strategic merge patch support
+- **CRD Support**: Automatic registration and schema validation
+- **Multi-Version CRDs**: Support for CRDs with multiple API versions
+- **Embedded CRDs**: Load CRDs from `go:embed` byte data
+- **Flexible API**: Functional options for easy configuration
 
 ## Quick Start
 
 ### Basic Usage
 
 ```go
-import (
-    "github.com/authzed/controller-idioms/client/fake"
-    apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
-    "k8s.io/apimachinery/pkg/runtime"
+import "github.com/authzed/controller-idioms/client/fake"
+
+// Basic client
+client := fake.NewClient(scheme)
+
+// With CRDs and initial objects
+client := fake.NewClient(scheme,
+    fake.WithCRDs(crd1, crd2),
+    fake.WithObjects(existingObject),
 )
 
-func TestMyController(t *testing.T) {
-    scheme := runtime.NewScheme()
-    
-    // Create a fake client with CRDs
-    client := fake.NewFakeDynamicClientWithCRDs(scheme, []*apiextensionsv1.CustomResourceDefinition{
-        myCRD,
-    })
-    
-    // Use the client in your tests...
-}
+// With embedded CRD files
+client := fake.NewClient(scheme,
+    fake.WithCRDBytes(embeddedCRDs1, embeddedCRDs2),
+)
 ```
 
-### Using Embedded CRDs
-
-The most convenient way to use CRDs in tests is with `go:embed`:
+### Using go:embed
 
 ```go
-package mycontroller_test
-
-import (
-    "context"
-    _ "embed"
-    "testing"
-    
-    "github.com/authzed/controller-idioms/client/fake"
-    "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
-    "k8s.io/apimachinery/pkg/runtime"
-    "k8s.io/apimachinery/pkg/runtime/schema"
-)
-
-// Embed your CRDs directly into the test binary
 //go:embed testdata/my-crds.yaml
 var embeddedCRDs []byte
 
-func TestWithEmbeddedCRDs(t *testing.T) {
-    scheme := runtime.NewScheme()
-    
-    // Create client with embedded CRDs
-    client := fake.NewFakeDynamicClientWithCRDBytes(scheme, embeddedCRDs)
+func TestMyController(t *testing.T) {
+    client := fake.NewClient(scheme, fake.WithCRDBytes(embeddedCRDs))
 
-    // Create a custom resource
+    // Create custom resources
     myResource := &unstructured.Unstructured{
         Object: map[string]interface{}{
             "apiVersion": "example.com/v1",
             "kind":       "MyResource",
-            "metadata": map[string]interface{}{
-                "name":      "test-resource",
-                "namespace": "default",
-            },
-            "spec": map[string]interface{}{
-                "replicas": 3,
-            },
+            "metadata":   map[string]interface{}{"name": "test"},
+            "spec":       map[string]interface{}{"replicas": 3},
         },
     }
 
     gvr := schema.GroupVersionResource{
-        Group:    "example.com",
-        Version:  "v1",
-        Resource: "myresources",
+        Group: "example.com", Version: "v1", Resource: "myresources",
     }
 
-    // Test CRUD operations
     created, err := client.Resource(gvr).Namespace("default").Create(
         context.TODO(), myResource, metav1.CreateOptions{},
     )
-    // ... rest of test
+    // Test your controller logic...
 }
 ```
 
-### Multiple CRD Files
+## API Reference
 
-You can combine multiple embedded files:
+### NewClient (Recommended)
 
 ```go
-//go:embed testdata/widgets.yaml
-var widgetCRD []byte
-
-//go:embed testdata/gadgets.yaml
-var gadgetCRD []byte
-
-func TestMultipleCRDs(t *testing.T) {
-    // Combine multiple CRD files
-    combinedCRDs := append(widgetCRD, []byte("\n---\n")...)
-    combinedCRDs = append(combinedCRDs, gadgetCRD...)
-    
-    scheme := runtime.NewScheme()
-    client := fake.NewFakeDynamicClientWithCRDBytes(scheme, combinedCRDs)
-    
-    // Both CRDs are now available...
-}
+func NewClient(scheme *runtime.Scheme, opts ...ClientOption) dynamic.Interface
 ```
 
-### Multi-Version CRDs
+Main constructor with functional options:
 
-The fake client fully supports CRDs with multiple versions:
+- `WithCRDs(crds...)` - Add CRD objects
+- `WithCRDBytes(data...)` - Add CRDs from YAML/JSON bytes
+- `WithCustomGVRMappings(mappings)` - Custom GVR to ListKind mappings
+- `WithOpenAPISpec(path)` - Custom OpenAPI spec file
+- `WithObjects(objects...)` - Initial objects in the client
 
-```yaml
-# testdata/multi-version-crd.yaml
-apiVersion: apiextensions.k8s.io/v1
-kind: CustomResourceDefinition
-metadata:
-  name: apps.example.com
-spec:
-  group: example.com
-  names:
-    kind: App
-    plural: apps
-    singular: app
-  scope: Namespaced
-  versions:
-  - name: v1alpha1
-    served: true
-    storage: false
-    schema:
-      openAPIV3Schema:
-        type: object
-        properties:
-          spec:
-            type: object
-            properties:
-              image:
-                type: string
-  - name: v1
-    served: true
-    storage: true
-    schema:
-      openAPIV3Schema:
-        type: object
-        properties:
-          spec:
-            type: object
-            properties:
-              image:
-                type: string
-              replicas:
-                type: integer
-```
+### Other Constructors
+
+These constructors are provided to mirror the upstream dynamic client interface,
+but they are less flexible than `NewClient`:
 
 ```go
-func TestMultiVersion(t *testing.T) {
-    client := fake.NewFakeDynamicClientWithCRDBytes(scheme, embeddedCRD)
-    
-    // Create resources using different API versions
-    v1alpha1GVR := schema.GroupVersionResource{
-        Group: "example.com", Version: "v1alpha1", Resource: "apps",
-    }
-    
-    v1GVR := schema.GroupVersionResource{
-        Group: "example.com", Version: "v1", Resource: "apps",
-    }
-    
-    // Both versions work independently
-    _, err := client.Resource(v1alpha1GVR).Create(/* ... */)
-    _, err = client.Resource(v1GVR).Create(/* ... */)
-}
+func NewFakeDynamicClient(scheme *runtime.Scheme, objects ...runtime.Object) dynamic.Interface
+func NewFakeDynamicClientWithCustomListKinds(scheme *runtime.Scheme, gvrToListKind map[schema.GroupVersionResource]string, objects ...runtime.Object) dynamic.Interface
 ```
 
-## Available Constructors
-
-### `NewFakeDynamicClient(scheme)`
-
-Basic fake client without CRD support.
-
-### `NewFakeDynamicClientWithCRDs(scheme, crds, objects...)`
-
-Fake client with CRD support using parsed CRD objects.
-
-### `NewFakeDynamicClientWithCRDBytes(scheme, crdData, objects...)`
-
-Fake client with CRDs loaded from embedded byte data. Supports YAML and JSON, multiple documents separated by `---`.
-
-### `NewFakeDynamicClientWithCRDBytesAndSpec(scheme, crdData, specPath, objects...)`
-
-Like `NewFakeDynamicClientWithCRDBytes` but allows specifying a custom OpenAPI spec file.
-
-### `NewFakeDynamicClientWithOpenAPISpec(scheme, specPath, crds, objects...)`
-
-Fake client with custom OpenAPI spec support for testing against different Kubernetes versions.
-
-## CRD File Format
-
-The `crdData` parameter accepts:
+## CRD Format
 
-- Single CRD in YAML or JSON format
-- Multiple CRDs separated by `---` (YAML multi-document format)
-- Mixed documents (non-CRD documents are ignored)
-
-Example multi-document format:
+Supports YAML and JSON, single or multi-document:
 
 ```yaml
 ---
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   name: widgets.example.com
-# ... widget CRD spec
+spec:
+  group: example.com
+  names:
+    kind: Widget
+    plural: widgets
+  # ... rest of CRD spec
 ---
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   name: gadgets.example.com
-# ... gadget CRD spec
+# ... second CRD
 ```
 
-## Error Handling
+## Examples
 
-All constructors panic on errors since they're designed for test usage. Common issues:
+### Multiple CRD Sources
 
-- **Invalid YAML/JSON**: Ensure your embedded files are valid
-- **Missing schema**: CRDs without OpenAPI schemas are supported but won't have validation
-- **Invalid CRD**: Non-CRD documents in the input are silently ignored
-
-## Best Practices
-
-1. **Use `go:embed`**: Embed CRDs directly in your test files for better maintainability
-2. **Version your CRDs**: Test against multiple API versions if your controller supports them
-3. **Separate test data**: Keep CRD files in a `testdata/` directory
-4. **Validate schemas**: Include proper OpenAPI v3 schemas in your CRDs for realistic testing
-5. **Test field management**: Use server-side apply to test field management behavior
-
-## Server-Side Apply Support
+```go
+client := fake.NewClient(scheme,
+    fake.WithCRDs(parsedCRD),                    // From CRD objects
+    fake.WithCRDBytes(widgetCRDs, gadgetCRDs),   // From embedded bytes
+    fake.WithObjects(existingResources...),      // Pre-existing objects
+)
+```
 
-The fake client supports server-side apply with proper field management:
+### Server-Side Apply
 
 ```go
-// Apply with field manager
 applied, err := client.Resource(gvr).Namespace("default").Apply(
-    context.TODO(), "resource-name", resource, 
+    context.TODO(), "resource-name", resource,
     metav1.ApplyOptions{
         FieldManager: "my-controller",
-        Force:        true, // Use when conflicts are expected
+        Force:        true,
     },
 )
 ```
 
-The fake client will track field ownership and handle strategic merge patches according to the CRD's OpenAPI schema.
+### Multi-Version CRDs
+
+```go
+// Different versions of the same resource
+v1alpha1GVR := schema.GroupVersionResource{Group: "example.com", Version: "v1alpha1", Resource: "apps"}
+v1GVR := schema.GroupVersionResource{Group: "example.com", Version: "v1", Resource: "apps"}
+
+// Both work independently
+client.Resource(v1alpha1GVR).Create(...)
+client.Resource(v1GVR).Create(...)
+```