Add idempotency core request lifecycle API with pluggable store (#35)

Author: Copilot

idempotency/memory-store.lisp

@@ -0,0 +1,72 @@
+(defpackage #:io.github.cl-sdk.wst.idempotency.memory-store
+  (:use #:cl #:io.github.cl-sdk.wst.idempotency.store)
+  (:import-from #:io.github.cl-sdk.wst.idempotency
+                #:idempotency-engine)
+  (:documentation "In-memory idempotency backend.
+
+Suitable for single-process scenarios; not thread-safe.")
+  (:export
+   #:memory-idempotency-engine))
+
+(in-package #:io.github.cl-sdk.wst.idempotency.memory-store)
+
+(defclass memory-idempotency-engine (idempotency-engine)
+  ((table :initarg :table
+          :initform (make-hash-table :test #'equal)
+          :reader memory-idempotency-engine-table))
+  (:documentation "Hash-table-backed in-memory idempotency engine.
+Not thread-safe.
+
+Instantiate with MAKE-INSTANCE and optional initargs:
+- :table hash table used to persist entries (defaults to (make-hash-table :test #'equal))
+- :ttl-seconds, :clock, :cache-response-p (inherited from idempotency-engine)."))
+
+(defun %expired-p (entry now)
+  (and entry
+       (idempotency-entry-expires-at entry)
+       (>= now (idempotency-entry-expires-at entry))))
+
+(defmethod create-entry ((engine memory-idempotency-engine) key fingerprint ttl-seconds now)
+  (let* ((table (memory-idempotency-engine-table engine))
+         (entry (gethash key table)))
+    (when (%expired-p entry now)
+      (remhash key table)
+      (setf entry nil))
+    (cond
+      ((null entry)
+       (let ((new-entry (make-idempotency-entry
+                         :state :processing
+                         :fingerprint fingerprint
+                         :response nil
+                         :expires-at (+ now ttl-seconds))))
+         (setf (gethash key table) new-entry)
+         (values :started new-entry)))
+      ((not (string= fingerprint (idempotency-entry-fingerprint entry)))
+       (values :conflict entry))
+      ((eq :completed (idempotency-entry-state entry))
+       (values :replay entry))
+      (t
+       (values :in-progress entry)))))
+
+(defmethod update-entry ((engine memory-idempotency-engine) key fingerprint response ttl-seconds now)
+  (let* ((table (memory-idempotency-engine-table engine))
+         (entry (gethash key table)))
+    (when (%expired-p entry now)
+      (remhash key table)
+      (setf entry nil))
+    (when (and entry
+               (eq :processing (idempotency-entry-state entry))
+               (string= fingerprint (idempotency-entry-fingerprint entry)))
+      (setf (idempotency-entry-state entry) :completed
+            (idempotency-entry-response entry) response
+            (idempotency-entry-expires-at entry) (+ now ttl-seconds))
+      t)))
+
+(defmethod delete-entry ((engine memory-idempotency-engine) key fingerprint)
+  (let* ((table (memory-idempotency-engine-table engine))
+         (entry (gethash key table)))
+    (when (and entry
+               (eq :processing (idempotency-entry-state entry))
+               (string= fingerprint (idempotency-entry-fingerprint entry)))
+      (remhash key table)
+      t)))

idempotency/package.lisp

@@ -0,0 +1,104 @@
+(defpackage #:io.github.cl-sdk.wst.idempotency
+  (:use #:cl)
+  (:documentation "Core idempotency-key primitives independent of HTTP objects.")
+  (:import-from #:io.github.cl-sdk.wst.idempotency.store
+                #:create-entry
+                #:update-entry
+                #:delete-entry
+                #:idempotency-entry-response)
+  (:export
+   #:cached-response
+   #:make-cached-response
+   #:cached-response-status
+   #:cached-response-headers
+   #:cached-response-content
+   #:idempotency-engine
+   #:make-idempotency-engine
+   #:idempotency-engine-ttl-seconds
+   #:idempotency-engine-clock
+   #:idempotency-engine-cache-response-p
+   #:valid-idempotency-key-p
+   #:register-request
+   #:drop-request
+   #:store-response))
+
+(in-package #:io.github.cl-sdk.wst.idempotency)
+
+(defstruct cached-response
+  "Serializable response snapshot for replay."
+  status
+  headers
+  content)
+
+(defclass idempotency-engine ()
+  ((ttl-seconds :initarg :ttl-seconds
+                :initform 86400
+                :reader idempotency-engine-ttl-seconds)
+   (clock :initarg :clock
+          :initform #'get-universal-time
+          :reader idempotency-engine-clock)
+   (cache-response-p :initarg :cache-response-p
+                     :initform (lambda (response)
+                                 (< (cached-response-status response) 500))
+                     :reader idempotency-engine-cache-response-p))
+  (:documentation "Core idempotency orchestration object.
+
+Engine subclasses can define their own storage slots and specialize
+io.github.cl-sdk.wst.idempotency.store:create-entry,
+io.github.cl-sdk.wst.idempotency.store:update-entry and
+io.github.cl-sdk.wst.idempotency.store:delete-entry for storage behavior.
+For a complete engine implementation, specialize all three methods."))
+
+(defgeneric register-request (engine scope key fingerprint)
+  (:documentation "Register lifecycle processing ownership for SCOPE/KEY/FINGERPRINT.
+
+Returns two values:
+- DECISION: one of :started, :replay, :in-progress, :conflict
+- PAYLOAD: cached-response for :replay, NIL otherwise."))
+
+(defgeneric store-response (engine scope key fingerprint response)
+  (:documentation "Persist RESPONSE for SCOPE/KEY/FINGERPRINT.
+
+Returns T when completion happened, NIL otherwise."))
+
+(defgeneric drop-request (engine scope key fingerprint)
+  (:documentation "Release processing lock for SCOPE/KEY/FINGERPRINT.
+
+Returns T when release happened, NIL otherwise."))
+
+(defun make-idempotency-engine ()
+  (error "No default store-backed idempotency engine is provided in io.github.cl-sdk.wst.idempotency. Use a concrete engine implementation such as (make-instance 'io.github.cl-sdk.wst.idempotency.memory-store:memory-idempotency-engine) or your own subclass."))
+
+(defun valid-idempotency-key-p (value)
+  "Return T when VALUE is a non-empty key of at most 255 chars.
+
+Key formatting/normalization is caller-managed."
+  (and (stringp value)
+       (not (string= "" value))
+       (<= (length value) 255)))
+
+(defmethod register-request ((engine idempotency-engine) scope key fingerprint)
+  (multiple-value-bind (status entry)
+      (create-entry engine
+                    (list scope key)
+                    fingerprint
+                    (idempotency-engine-ttl-seconds engine)
+                    (funcall (idempotency-engine-clock engine)))
+    (ecase status
+      (:started (values :started nil))
+      (:in-progress (values :in-progress nil))
+      (:conflict (values :conflict nil))
+      (:replay (values :replay (idempotency-entry-response entry))))))
+
+(defmethod store-response ((engine idempotency-engine) scope key fingerprint response)
+  (update-entry engine
+                (list scope key)
+                fingerprint
+                response
+                (idempotency-engine-ttl-seconds engine)
+                (funcall (idempotency-engine-clock engine))))
+
+(defmethod drop-request ((engine idempotency-engine) scope key fingerprint)
+  (delete-entry engine
+                (list scope key)
+                fingerprint))

idempotency/store.lisp

@@ -0,0 +1,47 @@
+(defpackage #:io.github.cl-sdk.wst.idempotency.store
+  (:use #:cl)
+  (:documentation "Storage backend protocol for idempotency key tracking.
+
+Implementations can provide atomic semantics for create/update/delete entry
+operations in single-node or distributed stores.")
+  (:export
+   #:idempotency-entry
+   #:make-idempotency-entry
+   #:idempotency-entry-state
+   #:idempotency-entry-fingerprint
+   #:idempotency-entry-response
+   #:idempotency-entry-expires-at
+   #:create-entry
+   #:update-entry
+   #:delete-entry))
+
+(in-package #:io.github.cl-sdk.wst.idempotency.store)
+
+(defstruct idempotency-entry
+  "Stored lifecycle record for a key.
+
+STATE is one of:
+- :processing
+- :completed"
+  state
+  fingerprint
+  response
+  expires-at)
+
+(defgeneric create-entry (store key fingerprint ttl-seconds now)
+  (:documentation "Try to claim KEY for FINGERPRINT.
+
+Returns two values:
+- STATUS keyword: one of :started, :replay, :in-progress, :conflict
+- ENTRY (or NIL): an idempotency-entry when useful for caller decisions."))
+
+(defgeneric update-entry (store key fingerprint response ttl-seconds now)
+  (:documentation "Persist RESPONSE as completed for KEY/FINGERPRINT.
+
+Returns T when completion happened, NIL otherwise."))
+
+(defgeneric delete-entry (store key fingerprint)
+  (:documentation "Release a processing entry for KEY/FINGERPRINT.
+
+Used when the current request should not be cached (for example 5xx).
+Returns T when release happened, NIL otherwise."))

io.github.cl-sdk.wst.idempotency.asd

@@ -0,0 +1,9 @@
+(asdf:defsystem #:io.github.cl-sdk.wst.idempotency
+  :description "Core idempotency-key lifecycle and replay policy."
+  :author "Bruno Dias"
+  :license "Unlicense"
+  :version "0.1.0"
+  :depends-on (#:io.github.cl-sdk.wst.idempotency.store)
+  :pathname "idempotency"
+  :serial t
+  :components ((:file "package")))

io.github.cl-sdk.wst.idempotency.memory-store.asd

@@ -0,0 +1,10 @@
+(asdf:defsystem #:io.github.cl-sdk.wst.idempotency.memory-store
+  :description "Built-in in-memory storage backend for idempotency keys."
+  :author "Bruno Dias"
+  :license "Unlicense"
+  :version "0.1.0"
+  :depends-on (#:io.github.cl-sdk.wst.idempotency.store
+               #:io.github.cl-sdk.wst.idempotency)
+  :pathname "idempotency"
+  :serial t
+  :components ((:file "memory-store")))

io.github.cl-sdk.wst.idempotency.store.asd

@@ -0,0 +1,9 @@
+(asdf:defsystem #:io.github.cl-sdk.wst.idempotency.store
+  :description "Storage backend protocol for idempotency keys."
+  :author "Bruno Dias"
+  :license "Unlicense"
+  :version "0.1.0"
+  :depends-on ()
+  :pathname "idempotency"
+  :serial t
+  :components ((:file "store")))

io.github.cl-sdk.wst.idempotency.test.asd

@@ -0,0 +1,12 @@
+(asdf:defsystem #:io.github.cl-sdk.wst.idempotency.test
+  :description "Tests for io.github.cl-sdk.wst.idempotency."
+  :author "Bruno Dias"
+  :license "Unlicense"
+  :version "0.1.0"
+  :depends-on (#:io.github.cl-sdk.wst.test.support
+               #:io.github.cl-sdk.wst.idempotency.store
+               #:io.github.cl-sdk.wst.idempotency.memory-store
+               #:io.github.cl-sdk.wst.idempotency)
+  :pathname "t"
+  :serial t
+  :components ((:file "idempotency-tests")))

io.github.cl-sdk.wst.test.asd

@@ -7,6 +7,7 @@
                #:io.github.cl-sdk.wst.routing.dsl.test
                #:io.github.cl-sdk.wst.circuit-breaker.test
                #:io.github.cl-sdk.wst.rate-limit.test
+               #:io.github.cl-sdk.wst.idempotency.test
                #:io.github.cl-sdk.wst.cors.test
                #:io.github.cl-sdk.wst.routing.woo.test
                #:io.github.cl-sdk.wst.routing.response.dsl.test

readme.md

@@ -19,6 +19,7 @@ Behavior is built from pipelines and composition, where middleware and handlers
 - CORS middleware
 - Static file routing
 - Rate limiting with pluggable stores
+- Idempotency core lifecycle API with pluggable stores
 - Circuit breaker core and routing middleware integration
 - Accept-aware response selection helpers (`io.github.cl-sdk.wst.request-accept`)
 - W3C Trace Context propagation (`traceparent`/`tracestate`) with routing adapter (`io.github.cl-sdk.wst.trace-context`)