@cqrs-ddd/pipeline-idempotency
Αποτρέπει τα διπλότυπα commands ανά κλειδί λειτουργίας. Όσο η εγγραφή ενός κλειδιού είναι ενεργή, μια δεύτερη κλήση με το ίδιο κλειδί δεν εκτελεί τον handler: λαμβάνει την αποθηκευμένη απάντηση όταν η πρώτη κλήση έχει ολοκληρωθεί, και απορρίπτεται με HTTP 409 Conflict όσο η πρώτη κλήση εκτελείται ακόμη. Η επαναχρησιμοποίηση του ίδιου κλειδιού με τροποποιημένο payload απορρίπτεται με HTTP 422 Unprocessable Entity.
Πρόκειται για αποφυγή διπλοτύπων μέσα στη διάρκεια ζωής μιας εγγραφής, όχι για εκτέλεση ακριβώς μία φορά (exactly-once): η ενότητα Εγγυήσεις και όρια απαριθμεί πότε ένας handler μπορεί να εκτελεστεί ξανά για το ίδιο κλειδί.
Περιλαμβάνει ενσωματωμένα stores για memory (testing), Redis και PostgreSQL με υποστήριξη επαλήθευσης replay ανά scope δικαιωμάτων.
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση»Τα stores δέχονται client που εγκαθιστά και συνδέει η εφαρμογή:
- Redis: node-redis client (
redis4 ή νεότερο) - PostgreSQL:
pgpool ή client
Μηχανή κατάστασης & Κύκλος ζωής εκτέλεσης
Ενότητα με τίτλο «Μηχανή κατάστασης & Κύκλος ζωής εκτέλεσης»Το IdempotencyBehavior συντονίζει τις καταστάσεις εκτέλεσης μέσω ατομικών λειτουργιών:
Εγγυήσεις και όρια
Ενότητα με τίτλο «Εγγυήσεις και όρια»Με store του οποίου η δέσμευση είναι ατομική, όπως τα τρία ενσωματωμένα stores, το behavior εγγυάται ότι:
- Από πολλές κλήσεις με το ίδιο κλειδί, όσο η εγγραφή του είναι ενεργή, μία εκτελεί τον handler. Οι υπόλοιπες απορρίπτονται με
in_progressόσο εκείνη εκτελείται και λαμβάνουν την αποθηκευμένη απάντησή της μόλις ολοκληρωθεί. - Μια ολοκληρωμένη απάντηση επιστρέφεται ξανά μέχρι να λήξει η εγγραφή της,
ttlμετά την ολοκλήρωση. - Μόνο η εκτέλεση που κατέχει μια δέσμευση την ολοκληρώνει ή την απελευθερώνει, ώστε μια εκτέλεση που ξεπερνά τη διάρκεια της δέσμευσής της να μην αντικαθιστά ούτε να διαγράφει ποτέ μια νεότερη.
Δεν εγγυάται ότι ο handler εκτελείται μία φορά. Ο handler μπορεί να εκτελεστεί ξανά για το ίδιο κλειδί όταν:
- Λήγει η εγγραφή. Το
ttlορίζει τη διάρκεια τόσο της δέσμευσης σε εξέλιξη όσο και της ολοκληρωμένης εγγραφής. Ένας handler που εκτελείται περισσότερο από τοttlχάνει τη δέσμευσή του, και η επόμενη κλήση με το κλειδί εκτελεί τον handler δεύτερη φορά· η πρώτη εκτέλεση επιστρέφει κανονικά το αποτέλεσμά της, με τοIDEMPOTENCY_OWNERSHIP_LOST_ITEM_TOKENορισμένο στο context. Μια διεργασία που σταματά κατά τη διάρκεια του handler αφήνει πίσω τη δέσμευσή της: οι επαναλήψεις απορρίπτονται μεin_progressμέχρι να λήξει η δέσμευση, και η πρώτη επανάληψη μετά τη λήξη εκτελεί ξανά τον handler. - Ο handler αποτυγχάνει. Με
releaseOnError: trueη δέσμευση διαγράφεται και μια επανάληψη εκτελεί ξανά τον handler, μαζί με ό,τι έκανε η αποτυχημένη προσπάθεια πριν αποτύχει. Μεfalseη δέσμευση παραμένει μέχρι να λήξει και οι επαναλήψεις απορρίπτονται μεin_progress. - Η απάντηση δεν μπορεί να αποθηκευτεί. Όταν ο handler επιτυγχάνει αλλά η απάντησή του δεν είναι serializable, ή το store απορρίπτει την εγγραφή, η κλήση ρίχνει
IdempotencyCompletionErrorμεexecutionSucceeded: trueκαιphase'snapshot'ή'store'. Οι παρενέργειες έχουν συμβεί και δεν έχει αποθηκευτεί απάντηση: μια επανάληψη απορρίπτεται μεin_progressόσο η δέσμευση είναι ενεργή και εκτελεί ξανά τον handler μετά τη λήξη της. - Το store χάνει την εγγραφή ή δεν είναι κοινόχρηστο. Το
MemoryIdempotencyStoreαποτρέπει διπλότυπα μέσα σε μία διεργασία και ξεχνά κάθε εγγραφή όταν η διεργασία σταματήσει. Πολλά instances χρειάζονται store στο οποίο έχουν όλα πρόσβαση, και οι παραπάνω εγγυήσεις είναι τόσο ανθεκτικές όσο το store αυτό.
Η εγγραφή και οι παρενέργειες του handler είναι ξεχωριστές εγγραφές: το behavior δεν τις τοποθετεί σε μία συναλλαγή (transaction), με κανένα store. Μια παρενέργεια που δεν πρέπει να επαναληφθεί χρειάζεται επομένως δική της προστασία. Περάστε ένα σταθερό αναγνωριστικό λειτουργίας σε εξωτερικό πάροχο που αποτρέπει διπλότυπα βάσει αυτού, όπως κάνει το παράδειγμα πληρωμής παρακάτω, ή κάντε την εγγραφή του ίδιου του handler να εξαρτάται από αυτό το αναγνωριστικό.
1. Plain Node.js / Μηχανή Pipeline
Ενότητα με τίτλο «1. Plain Node.js / Μηχανή Pipeline»Το αναγνωριστικό λειτουργίας περνά και στον πάροχο πληρωμών. Η εγγραφή του pipeline από μόνη της δεν αποτρέπει δεύτερη χρέωση μετά από διεργασία που σταμάτησε ή δέσμευση που έληξε· την αποτρέπει ο έλεγχος διπλοτύπων του ίδιου του παρόχου πάνω στο ίδιο αναγνωριστικό.
2. Standalone CQRS (@cqrs-ddd/cqrs)
Ενότητα με τίτλο «2. Standalone CQRS (@cqrs-ddd/cqrs)»3. NestJS (@cqrs-ddd/nestjs)
Ενότητα με τίτλο «3. NestJS (@cqrs-ddd/nestjs)»Αποθηκευτικά Backends
Ενότητα με τίτλο «Αποθηκευτικά Backends»Memory Store (MemoryIdempotencyStore)
Ενότητα με τίτλο «Memory Store (MemoryIdempotencyStore)»Ιδανικό για unit tests και περιβάλλον ανάπτυξης ενός node. Οι εγγραφές ζουν μέσα στη διεργασία και χάνονται όταν αυτή σταματήσει:
Redis Store (RedisIdempotencyStore)
Ενότητα με τίτλο «Redis Store (RedisIdempotencyStore)»Μοιράζεται τις εγγραφές μεταξύ instances, με χρήση ατομικών εντολών Redis:
PostgreSQL Store (PostgresIdempotencyStore)
Ενότητα με τίτλο «PostgreSQL Store (PostgresIdempotencyStore)»Μοιράζεται τις εγγραφές μεταξύ instances σε πίνακα της PostgreSQL, χωρίς ξεχωριστό Redis. Το store εκτελεί τα δικά του statements· μια εγγραφή δεν γράφεται μέσα στη συναλλαγή του handler:
Διαχωρισμός κλειδιών (Partitioned Keys)
Ενότητα με τίτλο «Διαχωρισμός κλειδιών (Partitioned Keys)»Τα κλειδιά idempotency πρέπει να είναι αυστηρά απομονωμένα ανά tenant και principal προς αποφυγή επιθέσεων σύγκρουσης κλειδιών μεταξύ tenants ή χρηστών:
| Επιλογή Factory | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
principal |
(ctx) => string | string[] | undefined |
υποχρεωτικό | Ταυτοποιεί τον καλούντα από αυθεντικοποιημένο context. Ρίχνει MissingIdempotencyPartitionError αν απουσιάζει. |
operation |
(ctx) => string | undefined |
υποχρεωτικό | Μοναδικό αναγνωριστικό λειτουργίας πελάτη (π.χ. από επικεφαλίδα Idempotency-Key). |
onMissingOperation |
'throw' | 'skip' |
'throw' |
Με 'throw', αιτήματα χωρίς id αποτυγχάνουν άμεσα. Με 'skip', εκτελούνται χωρίς παρακολούθηση idempotency. |
action |
string |
ctx.requestName |
Λογικό όνομα λειτουργίας ενσωματωμένο στο κλειδί. |
version |
string |
undefined |
Αρχικό τμήμα namespace. Αλλαγή του ακυρώνει όλες τις αποθηκευμένες εγγραφές. |
includeTenant |
boolean |
true |
Προσαρτά το ενεργό tenant ID στο κλειδί. |
requireTenant |
boolean |
includeTenant |
Ρίχνει MissingIdempotencyPartitionError αν λείπει το tenant. |
Μορφή παραγόμενου κλειδιού:
Ασφάλεια & Επαλήθευση Scope στο Replay
Ενότητα με τίτλο «Ασφάλεια & Επαλήθευση Scope στο Replay»Ένα cache ή idempotency hit επιστρέφει αποθηκευμένα δεδομένα χωρίς να καλέσει τον handler ή τους εσωτερικούς ελέγχους δικαιωμάτων οντοτήτων.
Για να αποτρέψετε αναβάθμιση προνομίων (privilege escalation) όταν τα δικαιώματα αλλάζουν μεταξύ αιτημάτων, δηλώστε replayScopeFactory:
Αν τα δικαιώματα του καλούντος έχουν αλλάξει μεταξύ της αρχικής εκτέλεσης και του διπλότυπου αιτήματος, το αποθηκευμένο digest δεν θα ταιριάζει. Το αίτημα απορρίπτεται με IdempotencyConflictError (reason: 'replay_scope', HTTP 409 Conflict) αντί να επιστραφούν μη εξουσιοδοτημένα δεδομένα.
Επιλογές παραμετροποίησης
Ενότητα με τίτλο «Επιλογές παραμετροποίησης»| Επιλογή | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
keyFactory |
IdempotencyKeyFactory |
υποχρεωτικό | Συνάρτηση παραγωγής του string κλειδιού. |
ttl |
number |
86_400_000 (24h) |
Διάρκεια ζωής σε milliseconds της δέσμευσης σε εξέλιξη και, με επανεκκίνηση κατά την ολοκλήρωση, της ολοκληρωμένης εγγραφής. Ορίστε το μεγαλύτερο από την πιο αργή εκτέλεση. |
scope |
DeclaredKind[] |
['command'] |
Είδη αιτημάτων στα οποία εφαρμόζεται το behavior. |
fingerprint |
boolean |
true |
Συγκρίνει SHA-256 hash του request payload. Αναντιστοιχία ρίχνει key_reuse (422). |
replayScopeFactory |
IdempotencyReplayScopeFactory |
undefined |
Υπολογίζει digest εξουσιοδότησης για ασφαλές replay. |
releaseOnError |
boolean |
true |
Διαγράφει τη δέσμευση όταν ο handler αποτυγχάνει, ώστε μια επανάληψη να εκτελέσει ξανά τον handler. Με false η δέσμευση παραμένει μέχρι να λήξει. |
HTTP αντιστοίχιση σφαλμάτων
Ενότητα με τίτλο «HTTP αντιστοίχιση σφαλμάτων»Το IdempotencyConflictError αντιστοιχίζεται σε HTTP απαντήσεις μέσω του @cqrs-ddd/pipeline-idempotency/http:
| Αιτία διένεξης (Conflict Reason) | HTTP Status | Περιγραφή |
|---|---|---|
in_progress |
409 Conflict | Μια εκτέλεση με το ίδιο κλειδί βρίσκεται ακόμη σε εξέλιξη. |
replay_scope |
409 Conflict | Η αποθηκευμένη απάντηση εξουσιοδοτήθηκε υπό διαφορετικό scope δικαιωμάτων. |
key_reuse |
422 Unprocessable Entity | Το ίδιο κλειδί στάλθηκε με διαφορετικό payload. |
Το IdempotencyCompletionError δεν έχει αντιστοίχιση σε HTTP: ο handler πέτυχε και η απάντησή του δεν αποθηκεύτηκε, οπότε η εφαρμογή αποφασίζει πώς θα απαντήσει στον καλούντα και αν απαιτείται έλεγχος συμφωνίας (reconciliation).
Σε εφαρμογές NestJS με @cqrs-ddd/nestjs, το ErrorFilter αντιστοιχίζει αυτά τα σφάλματα αυτόματα.