pepr 0.35.0 → 0.36.0

package/dist/sdk/sdk.d.ts

@@ -24,10 +24,12 @@ export declare function containers(request: PeprValidateRequest<a.Pod> | PeprMut
 export declare function writeEvent(cr: GenericKind, event: Partial<kind.CoreEvent>, eventType: string, eventReason: string, reportingComponent: string, reportingInstance: string): Promise<void>;
 /**
  * Get the owner reference for a custom resource
- * @param cr the custom resource to get the owner reference for
- * @returns the owner reference for the custom resource
+ * @param customResource the custom resource to get the owner reference for
+ * @param blockOwnerDeletion if true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed.
+ * @param controller if true, this reference points to the managing controller.
+ * @returns the owner reference array for the custom resource
  */
-export declare function getOwnerRefFrom(cr: GenericKind): V1OwnerReference[];
+export declare function getOwnerRefFrom(customResource: GenericKind, blockOwnerDeletion?: boolean, controller?: boolean): V1OwnerReference[];
 /**
  * Sanitize a resource name to make it a valid Kubernetes resource name.
  *

package/dist/sdk/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/sdk/sdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAO,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAGrD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9D,aAAa,CAAC,EAAE,YAAY,GAAG,gBAAgB,GAAG,qBAAqB,mDAgBxE;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAC9B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,iBAAiB,EAAE,MAAM,iBAwB1B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,GAAG,gBAAgB,EAAE,CAWnE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,UAYhD"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/sdk/sdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAO,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAGrD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9D,aAAa,CAAC,EAAE,YAAY,GAAG,gBAAgB,GAAG,qBAAqB,mDAgBxE;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAC9B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,iBAAiB,EAAE,MAAM,iBAwB1B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,cAAc,EAAE,WAAW,EAC3B,kBAAkB,CAAC,EAAE,OAAO,EAC5B,UAAU,CAAC,EAAE,OAAO,GACnB,gBAAgB,EAAE,CAcpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,UAYhD"}

package/package.json

@@ -13,7 +13,7 @@
     "/dist",
     "/src"
   ],
-  "version": "0.35.0",
+  "version": "0.36.0",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
   "scripts": {
@@ -39,18 +39,18 @@
   },
   "dependencies": {
     "@types/ramda": "0.30.2",
-    "express": "4.19.2",
+    "express": "4.21.0",
     "fast-json-patch": "3.1.1",
     "json-pointer": "^0.6.2",
-    "kubernetes-fluent-client": "3.0.2",
-    "pino": "9.3.2",
+    "kubernetes-fluent-client": "3.0.3",
+    "pino": "9.4.0",
     "pino-pretty": "11.2.2",
     "prom-client": "15.1.3",
     "ramda": "0.30.1"
   },
   "devDependencies": {
-    "@commitlint/cli": "19.4.1",
-    "@commitlint/config-conventional": "19.4.1",
+    "@commitlint/cli": "19.5.0",
+    "@commitlint/config-conventional": "19.5.0",
     "@fast-check/jest": "^2.0.1",
     "@jest/globals": "29.7.0",
     "@types/eslint": "9.6.1",

package/src/lib/capability.ts

@@ -198,12 +198,13 @@ export class Capability implements CapabilityExport {
         namespaces: [],
         labels: {},
         annotations: {},
+        deletionTimestamp: false,
       },
     };
 
     const bindings = this.#bindings;
     const prefix = `${this.#name}: ${model.name}`;
-    const commonChain = { WithLabel, WithAnnotation, Mutate, Validate, Watch, Reconcile };
+    const commonChain = { WithLabel, WithAnnotation, WithDeletionTimestamp, Mutate, Validate, Watch, Reconcile };
     const isNotEmpty = (value: object) => Object.keys(value).length > 0;
     const log = (message: string, cbString: string) => {
       const filteredObj = pickBy(isNotEmpty, binding.filters);
@@ -277,6 +278,12 @@ export class Capability implements CapabilityExport {
       return { ...commonChain, WithName };
     }
 
+    function WithDeletionTimestamp(): BindingFilter<T> {
+      Log.debug("Add deletionTimestamp filter");
+      binding.filters.deletionTimestamp = true;
+      return commonChain;
+    }
+
     function WithName(name: string): BindingFilter<T> {
       Log.debug(`Add name filter ${name}`, prefix);
       binding.filters.name = name;
@@ -301,6 +308,7 @@ export class Capability implements CapabilityExport {
         ...commonChain,
         InNamespace,
         WithName,
+        WithDeletionTimestamp,
       };
     }
 

package/src/lib/filter.test.ts

@@ -29,6 +29,7 @@ describe("Fuzzing shouldSkipRequest", () => {
             namespaces: fc.array(fc.string()),
             labels: fc.dictionary(fc.string(), fc.string()),
             annotations: fc.dictionary(fc.string(), fc.string()),
+            deletionTimestamp: fc.boolean(),
           }),
         }),
         fc.record({
@@ -41,6 +42,11 @@ describe("Fuzzing shouldSkipRequest", () => {
             version: fc.string(),
             kind: fc.string(),
           }),
+          object: fc.record({
+            metadata: fc.record({
+              deletionTimestamp: fc.option(fc.date()),
+            }),
+          }),
         }),
         fc.array(fc.string()),
         (binding, req, capabilityNamespaces) => {
@@ -69,6 +75,7 @@ describe("Property-Based Testing shouldSkipRequest", () => {
             namespaces: fc.array(fc.string()),
             labels: fc.dictionary(fc.string(), fc.string()),
             annotations: fc.dictionary(fc.string(), fc.string()),
+            deletionTimestamp: fc.boolean(),
           }),
         }),
         fc.record({
@@ -81,6 +88,11 @@ describe("Property-Based Testing shouldSkipRequest", () => {
             version: fc.string(),
             kind: fc.string(),
           }),
+          object: fc.record({
+            metadata: fc.record({
+              deletionTimestamp: fc.option(fc.date()),
+            }),
+          }),
         }),
         fc.array(fc.string()),
         (binding, req, capabilityNamespaces) => {
@@ -103,6 +115,7 @@ test("should reject when name does not match", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -121,6 +134,7 @@ test("should reject when kind does not match", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -139,6 +153,7 @@ test("should reject when group does not match", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -161,6 +176,7 @@ test("should reject when version does not match", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -179,6 +195,7 @@ test("should allow when group, version, and kind match", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -201,6 +218,7 @@ test("should allow when kind match and others are empty", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -219,6 +237,7 @@ test("should reject when teh capability namespace does not match", () => {
       namespaces: [],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -237,6 +256,7 @@ test("should reject when namespace does not match", () => {
       namespaces: ["bleh"],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -255,6 +275,7 @@ test("should allow when namespace is match", () => {
       namespaces: ["default", "unicorn", "things"],
       labels: {},
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -275,6 +296,7 @@ test("should reject when label does not match", () => {
         foo: "bar",
       },
       annotations: {},
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -290,7 +312,7 @@ test("should allow when label is match", () => {
     kind: podKind,
     filters: {
       name: "",
-
+      deletionTimestamp: false,
       namespaces: [],
       labels: {
         foo: "bar",
@@ -324,6 +346,7 @@ test("should reject when annotation does not match", () => {
       annotations: {
         foo: "bar",
       },
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -345,6 +368,7 @@ test("should allow when annotation is match", () => {
         foo: "bar",
         test: "test1",
       },
+      deletionTimestamp: false,
     },
     callback,
   };
@@ -368,6 +392,7 @@ test("should use `oldObject` when the operation is `DELETE`", () => {
     filters: {
       name: "",
       namespaces: [],
+      deletionTimestamp: false,
       labels: {
         "app.kubernetes.io/name": "cool-name-podinfo",
       },
@@ -382,3 +407,62 @@ test("should use `oldObject` when the operation is `DELETE`", () => {
 
   expect(shouldSkipRequest(binding, pod, [])).toBe(false);
 });
+
+test("should skip processing when deletionTimestamp is not present on pod", () => {
+  const binding = {
+    model: kind.Pod,
+    event: Event.Any,
+    kind: podKind,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {
+        foo: "bar",
+        test: "test1",
+      },
+      deletionTimestamp: true,
+    },
+    callback,
+  };
+
+  const pod = CreatePod();
+  pod.object.metadata = pod.object.metadata || {};
+  pod.object.metadata.annotations = {
+    foo: "bar",
+    test: "test1",
+    test2: "test2",
+  };
+
+  expect(shouldSkipRequest(binding, pod, [])).toBe(true);
+});
+
+test("should processing when deletionTimestamp is not present on pod", () => {
+  const binding = {
+    model: kind.Pod,
+    event: Event.Any,
+    kind: podKind,
+    filters: {
+      name: "",
+      namespaces: [],
+      labels: {},
+      annotations: {
+        foo: "bar",
+        test: "test1",
+      },
+      deletionTimestamp: true,
+    },
+    callback,
+  };
+
+  const pod = CreatePod();
+  pod.object.metadata = pod.object.metadata || {};
+  pod.object.metadata!.deletionTimestamp = new Date("2021-09-01T00:00:00Z");
+  pod.object.metadata.annotations = {
+    foo: "bar",
+    test: "test1",
+    test2: "test2",
+  };
+
+  expect(shouldSkipRequest(binding, pod, [])).toBe(false);
+});

package/src/lib/filter.ts

@@ -22,6 +22,15 @@ export function shouldSkipRequest(binding: Binding, req: AdmissionRequest, capab
   const { metadata } = srcObject || {};
   const combinedNamespaces = [...namespaces, ...capabilityNamespaces];
 
+  // Delete bindings do not work through admission with DeletionTimestamp
+  if (binding.event.includes(Event.Delete) && binding.filters?.deletionTimestamp) {
+    return true;
+  }
+
+  // Test for deletionTimestamp
+  if (binding.filters?.deletionTimestamp && !req.object.metadata?.deletionTimestamp) {
+    return true;
+  }
   // Test for matching operation
   if (!binding.event.includes(operation) && !binding.event.includes(Event.Any)) {
     return true;

package/src/lib/helpers.test.ts

@@ -1056,6 +1056,40 @@ describe("filterMatcher", () => {
     expect(result).toEqual("Ignoring Watch Callback: Cannot use a namespace filter in a namespace object.");
   });
 
+  test("return deletionTimestamp error when there is no deletionTimestamp in the object", () => {
+    const binding = {
+      filters: { deletionTimestamp: true },
+    };
+    const obj = {
+      metadata: {},
+    };
+    const capabilityNamespaces: string[] = [];
+    const result = filterNoMatchReason(
+      binding as unknown as Partial<Binding>,
+      obj as unknown as Partial<KubernetesObject>,
+      capabilityNamespaces,
+    );
+    expect(result).toEqual("Ignoring Watch Callback: Object does not have a deletion timestamp.");
+  });
+
+  test("return no deletionTimestamp error when there is a deletionTimestamp in the object", () => {
+    const binding = {
+      filters: { deletionTimestamp: true },
+    };
+    const obj = {
+      metadata: {
+        deletionTimestamp: "2021-01-01T00:00:00Z",
+      },
+    };
+    const capabilityNamespaces: string[] = [];
+    const result = filterNoMatchReason(
+      binding as unknown as Partial<Binding>,
+      obj as unknown as Partial<KubernetesObject>,
+      capabilityNamespaces,
+    );
+    expect(result).not.toEqual("Ignoring Watch Callback: Object does not have a deletion timestamp.");
+  });
+
   test("returns label overlap error when there is no overlap between binding and object labels", () => {
     const binding = {
       filters: { labels: { key: "value" } },

package/src/lib/helpers.ts

@@ -73,6 +73,11 @@ export function filterNoMatchReason(
   obj: Partial<KubernetesObject>,
   capabilityNamespaces: string[],
 ): string {
+  // binding deletionTimestamp filter and object deletionTimestamp dont match
+  if (binding.filters?.deletionTimestamp && !obj.metadata?.deletionTimestamp) {
+    return `Ignoring Watch Callback: Object does not have a deletion timestamp.`;
+  }
+
   // binding kind is namespace with a InNamespace filter
   if (binding.kind && binding.kind.kind === "Namespace" && binding.filters && binding.filters.namespaces.length !== 0) {
     return `Ignoring Watch Callback: Cannot use a namespace filter in a namespace object.`;

package/src/lib/queue.test.ts

@@ -1,58 +1,152 @@
-import { beforeEach, describe, expect, jest, test } from "@jest/globals";
-import { KubernetesObject } from "@kubernetes/client-node";
+import { afterEach, describe, expect, jest, it } from "@jest/globals";
 import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
 import { Queue } from "./queue";
 
+import Log from "./logger";
+jest.mock("./logger");
+
 describe("Queue", () => {
-  let queue: Queue<KubernetesObject>;
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it("is uniquely identifiable", () => {
+    const name = "kind/namespace";
+    const queue = new Queue(name);
+
+    const label = queue.label();
+
+    expect(label).toEqual(
+      expect.objectContaining({
+        // given name of queue
+        name,
+
+        // unique, generated value (to disambiguate similarly-named queues)
+        // <epoch timestamp (ms)>-<4 char hex>
+        uid: expect.stringMatching(/[0-9]{13}-[0-9a-f]{4}/),
+      }),
+    );
+  });
+
+  it("exposes runtime stats", async () => {
+    const name = "kind/namespace";
+    const queue = new Queue(name);
+
+    expect(queue.stats()).toEqual(
+      expect.objectContaining({
+        queue: queue.label(),
+        stats: { length: 0 },
+      }),
+    );
+
+    const kubeObj = { metadata: { name: "test-nm", namespace: "test-ns" } };
+    const watchCb = () =>
+      new Promise<void>(res => {
+        setTimeout(res, 100);
+      });
+
+    await Promise.all([
+      queue.enqueue(kubeObj, WatchPhase.Added, watchCb),
+      queue.enqueue(kubeObj, WatchPhase.Added, watchCb),
+      queue.enqueue(kubeObj, WatchPhase.Added, watchCb),
+      queue.enqueue(kubeObj, WatchPhase.Added, watchCb),
+    ]);
+
+    const logDebug = Log.debug as jest.Mock;
+    const stats = logDebug.mock.calls
+      .flat()
+      .map(m => JSON.stringify(m))
+      .filter(m => m.includes('"stats":'));
 
-  beforeEach(() => {
-    queue = new Queue();
+    [
+      '"length":1', // 1st entry runs near-immediately, so queue won't fill
+      '"length":1', // afterward, queue fills & unfills as callbacks process
+      '"length":2',
+      '"length":3',
+      '"length":3',
+      '"length":2',
+      '"length":1',
+      '"length":0',
+    ].map((exp, idx) => {
+      expect(stats[idx]).toEqual(expect.stringContaining(exp));
+    });
   });
 
-  test("enqueue should add a pod to the queue and return a promise", async () => {
-    const pod = {
-      metadata: { name: "test-pod", namespace: "test-pod" },
-    };
-    const promise = queue.enqueue(pod, WatchPhase.Added);
+  it("resolves when an enqueued event dequeues without error", async () => {
+    const name = "kind/namespace";
+    const queue = new Queue(name);
+
+    const kubeObj = { metadata: { name: "test-nm", namespace: "test-ns" } };
+    const watchCb = () =>
+      new Promise<void>(res => {
+        setTimeout(res, 10);
+      });
+
+    const promise = queue.enqueue(kubeObj, WatchPhase.Added, watchCb);
     expect(promise).toBeInstanceOf(Promise);
-    await promise;
+
+    await expect(promise).resolves.not.toThrow();
   });
 
-  test("dequeue should process pods in FIFO order", async () => {
-    const mockPod = {
-      metadata: { name: "test-pod", namespace: "test-namespace" },
-    };
-    const mockPod2 = {
-      metadata: { name: "test-pod-2", namespace: "test-namespace-2" },
-    };
-
-    // Enqueue two packages
-    const promise1 = queue.enqueue(mockPod, WatchPhase.Added);
-    const promise2 = queue.enqueue(mockPod2, WatchPhase.Modified);
-
-    // Wait for both promises to resolve
-    await promise1;
-    await promise2;
+  it("rejects when an enqueued event dequeues with error", async () => {
+    const name = "kind/namespace";
+    const queue = new Queue(name);
+
+    const kubeObj = { metadata: { name: "test-nm", namespace: "test-ns" } };
+    const watchCb = () =>
+      new Promise<void>((_, reject) => {
+        setTimeout(() => {
+          reject("oof");
+        }, 10);
+      });
+
+    const promise = queue.enqueue(kubeObj, WatchPhase.Added, watchCb);
+    expect(promise).toBeInstanceOf(Promise);
+
+    await expect(promise).rejects.toBe("oof");
   });
 
-  test("dequeue should handle errors in pod processing", async () => {
-    const mockPod = {
-      metadata: { name: "test-pod", namespace: "test-namespace" },
-    };
-    const error = new Error("reconciliation failed");
-    jest.spyOn(queue, "setReconcile").mockRejectedValueOnce(error as never);
-
-    try {
-      await queue.enqueue(mockPod, WatchPhase.Added);
-    } catch (e) {
-      expect(e).toBe(error);
-    }
-
-    // Ensure that the queue is ready to process the next pod
-    const mockPod2 = {
-      metadata: { name: "test-pod-2", namespace: "test-namespace-2" },
-    };
-    await queue.enqueue(mockPod2, WatchPhase.Modified);
+  it("processes events in FIFO order", async () => {
+    const name = "kind/namespace";
+    const queue = new Queue(name);
+
+    const kubeObj = { metadata: { name: "test-nm", namespace: "test-ns" } };
+    const watchA = () =>
+      new Promise<void>(resolve => {
+        setTimeout(() => {
+          Log.info("watchA");
+          resolve();
+        }, 15);
+      });
+    const watchB = () =>
+      new Promise<void>(resolve => {
+        setTimeout(() => {
+          Log.info("watchB");
+          resolve();
+        }, 10);
+      });
+    const watchC = () =>
+      new Promise<void>(resolve => {
+        setTimeout(() => {
+          Log.info("watchC");
+          resolve();
+        }, 5);
+      });
+
+    await Promise.all([
+      queue.enqueue(kubeObj, WatchPhase.Added, watchA),
+      queue.enqueue(kubeObj, WatchPhase.Added, watchB),
+      queue.enqueue(kubeObj, WatchPhase.Added, watchC),
+    ]);
+
+    const logInfo = Log.info as jest.Mock;
+    const calls = logInfo.mock.calls
+      .flat()
+      .map(m => JSON.stringify(m))
+      .filter(m => /"watch[ABC]"/.test(m));
+
+    ['"watchA"', '"watchB"', '"watchC"'].map((exp, idx) => {
+      expect(calls[idx]).toEqual(expect.stringContaining(exp));
+    });
   });
 });

package/src/lib/queue.ts

@@ -2,11 +2,15 @@
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 import { KubernetesObject } from "@kubernetes/client-node";
 import { WatchPhase } from "kubernetes-fluent-client/dist/fluent/types";
+import { randomBytes } from "node:crypto";
 import Log from "./logger";
 
+type WatchCallback = (obj: KubernetesObject, phase: WatchPhase) => Promise<void>;
+
 type QueueItem<K extends KubernetesObject> = {
   item: K;
-  type: WatchPhase;
+  phase: WatchPhase;
+  callback: WatchCallback;
   resolve: (value: void | PromiseLike<void>) => void;
   reject: (reason?: string) => void;
 };
@@ -15,16 +19,27 @@ type QueueItem<K extends KubernetesObject> = {
  * Queue is a FIFO queue for reconciling
  */
 export class Queue<K extends KubernetesObject> {
+  #name: string;
+  #uid: string;
   #queue: QueueItem<K>[] = [];
   #pendingPromise = false;
-  #reconcile?: (obj: KubernetesObject, type: WatchPhase) => Promise<void>;
 
-  constructor() {
-    this.#reconcile = async () => await new Promise(resolve => resolve());
+  constructor(name: string) {
+    this.#name = name;
+    this.#uid = `${Date.now()}-${randomBytes(2).toString("hex")}`;
+  }
+
+  label() {
+    return { name: this.#name, uid: this.#uid };
   }
 
-  setReconcile(reconcile: (obj: KubernetesObject, type: WatchPhase) => Promise<void>) {
-    this.#reconcile = reconcile;
+  stats() {
+    return {
+      queue: this.label(),
+      stats: {
+        length: this.#queue.length,
+      },
+    };
   }
 
   /**
@@ -32,12 +47,23 @@ export class Queue<K extends KubernetesObject> {
    * reconciled.
    *
    * @param item The object to reconcile
+   * @param type The watch phase requested for reconcile
+   * @param reconcile The callback to enqueue for reconcile
    * @returns A promise that resolves when the object is reconciled
    */
-  enqueue(item: K, type: WatchPhase) {
-    Log.debug(`Enqueueing ${item.metadata!.namespace}/${item.metadata!.name}`);
+  enqueue(item: K, phase: WatchPhase, reconcile: WatchCallback) {
+    const note = {
+      queue: this.label(),
+      item: {
+        name: item.metadata?.name,
+        namespace: item.metadata?.namespace,
+        resourceVersion: item.metadata?.resourceVersion,
+      },
+    };
+    Log.debug(note, "Enqueueing");
     return new Promise<void>((resolve, reject) => {
-      this.#queue.push({ item, type, resolve, reject });
+      this.#queue.push({ item, phase, callback: reconcile, resolve, reject });
+      Log.debug(this.stats(), "Queue stats - push");
       return this.#dequeue();
     });
   }
@@ -68,16 +94,25 @@ export class Queue<K extends KubernetesObject> {
       this.#pendingPromise = true;
 
       // Reconcile the element
-      if (this.#reconcile) {
-        Log.debug(`Reconciling ${element.item.metadata!.name}`);
-        await this.#reconcile(element.item, element.type);
-      }
+      const note = {
+        queue: this.label(),
+        item: {
+          name: element.item.metadata?.name,
+          namespace: element.item.metadata?.namespace,
+          resourceVersion: element.item.metadata?.resourceVersion,
+        },
+      };
+      Log.debug(note, "Reconciling");
+      await element.callback(element.item, element.phase);
+      Log.debug(note, "Reconciled");
 
       element.resolve();
     } catch (e) {
       Log.debug(`Error reconciling ${element.item.metadata!.name}`, { error: e });
       element.reject(e);
     } finally {
+      Log.debug(this.stats(), "Queue stats - shift");
+
       // Reset the pending promise flag
       Log.debug("Resetting pending promise and dequeuing");
       this.#pendingPromise = false;