Έκδοση 1.0.0-alpha.1τελευταία
Κεφάλαιο 2.19
Οι κανόνες που κληρονομεί κάθε επέκταση
Απομόνωση σε τρεις άξονες, υπολογιστική επεξεργασία μέσω UNO, AI (τεχνητή νοημοσύνη) μέσω του δρομολογητή, κλειδιά που ανήκουν στον οργανισμό και έλεγχοι αδειών χρήσης. Τι σημαίνει κάθε κανόνας για τον κώδικά σας, ποια πύλη (gate) τον επιβάλλει και γιατί τον κληρονομείτε αντί να τον γράφετε.
Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

Η πρώτη απόρριψη που έστειλε ποτέ το πρόσθετό μου (plugin) για τον έλεγχο ανωμαλιών ήταν σε εμένα. Είχα γράψει έναν δοκιμαστικό πελάτη (client) που υπέβαλλε έναν νέο έλεγχο με το αναγνωριστικό (id) του οργανισμού στο σώμα του αιτήματος (body), από συνήθεια από άλλη πλατφόρμα, και το πρόσθετο απάντησε πριν καν εκτελεστεί ο δικός μου χειριστής (handler):
{
"error": true,
"code": "TENANT_NOT_A_PARAMETER",
"message": "The request body names the organisation. Tenancy comes from the token.",
"resolved": ["tenant", "owner"],
"missing": [],
"troubleshooting": ["Remove organizationId from the body. The organisation is read from your sign-in."]
}Δεν είχα γράψει εγώ αυτόν τον έλεγχο. Συμπεριλαμβανόταν στον φρουρό εμβέλειας (scope guard) που το πρότυπο του SDK (software development kit) συνδέει σε κάθε διαδρομή (route) /api, και ενεργοποιείται ακόμη και όταν το αναγνωριστικό στο σώμα του αιτήματος είναι του ίδιου του καλούντος. Αυτό είναι το μοτίβο για ολόκληρο αυτό το κεφάλαιο: ένας μικρός αριθμός κανόνων, καθένας από τους οποίους επιβάλλεται από έναν μηχανισμό που κληρονομείτε, και καθένας με μια πύλη ελέγχου (gate) που οδηγεί σε αποτυχία τη δομή (build) σας αν ο κώδικάς σας την παρακάμψει. Στο Nexus, το πρόσθετό σας κληρονομεί την απομόνωσή του από την πλατφόρμα, και οι πύλες ελέγχου την επιθεωρούν.
Υπάρχουν πέντε κανόνες, και οι παρακάτω ενότητες τους εξετάζουν με τη σειρά: απομόνωση σε τρεις άξονες· υπολογιστική επεξεργασία (compute) που εκτελείται μόνο μέσω της αποστολής (dispatch) του UNO· AI (τεχνητή νοημοσύνη) που διέρχεται μόνο μέσω του AI Provider Router· κλειδιά μοντέλων που ανήκουν στον οργανισμό· και αδειοδοτημένες λειτουργίες που ελέγχονται έναντι της άδειας χρήσης. Κάθε αρχείο δήλωσης (manifest) επαναδιατυπώνει επίσης τρεις από αυτούς σε μία ενότητα προτάσεων.
Κανόνας 1: απομόνωση σε τρεις άξονες, από το επικυρωμένο αίτημα
Κάθε ανάγνωση και εγγραφή σε μια επέκταση οριοθετείται (scoped) σε τρεις άξονες, το ίδιο και κάθε κλήση εργαλείου και αποστολή δεξιότητας (skill dispatch).
| Άξονας | Στήλη | Απαντά στο | Πόσο αυστηρό είναι το όριο |
|---|---|---|---|
| Μισθωτής (Tenant) | organization_id |
Ποιος οργανισμός | Ένα αυστηρό όριο, που διασχίζεται μόνο μέσω μιας καταγεγραμμένης παραχώρησης αποκλειστικά για ανάγνωση |
| Ιδιοκτήτης (Owner) | owner_user_id |
Ποιο άτομο εντός του οργανισμού | Ιδιωτικό ακόμη και εντός του ίδιου οργανισμού, για οτιδήποτε προσωπικό |
| Μονάδα (Unit) | business_unit_id |
Ποιο τμήμα του οργανισμού | Ένας προαιρετικός φράκτης εντός ενός μισθωτή (tenant) |
Ο άξονας του κατόχου (owner) είναι αυτός στον οποίο κάνουν λάθος οι νεοεισερχόμενοι. Ένα γραμματοκιβώτιο είναι προσωπικό, όπως και μια αποθηκευμένη προβολή ή ένα γράφημα που προκύπτει από τα δεδομένα ενός ατόμου. Δύο μέλη του ίδιου οργανισμού, στην ίδια μονάδα και με τον ίδιο ρόλο, δεν βλέπουν το ένα τις εγγραφές (rows) που είναι οριοθετημένες στον κάτοχο του άλλου. Σε ένα αντικείμενο (artefact) οργανισμού, όπως μια έγκριση ή μια εγγραφή υπόθεσης για παράδειγμα, ο κάτοχος αποτελεί αντίθετα στοιχείο προέλευσης: καταγράφει ποιος ενήργησε, και οι αναγνώσεις οριοθετούνται στον μισθωτή ώστε το ίχνος ελέγχου (audit trail) να παραμένει ορατό στα άτομα που το χρειάζονται. Εσείς αποφασίζετε ανά πίνακα για ποιο είδος πρόκειται, και το επίπεδο αποθετηρίου (repository layer) το κωδικοποιεί — ποτέ ως ειδική περίπτωση σε μια διαδρομή.
Οι άξονες προέρχονται από το αυθεντικοποιημένο αίτημα και από πουθενά αλλού. Μια μεταβλητή περιβάλλοντος δεν μπορεί να τους παρέχει, ούτε μια παράμετρος ερωτήματος (query parameter), ένα τμήμα διαδρομής (path segment), μια κεφαλίδα πελάτη (client header) ή μια σταθερά δομής (build constant). Το SDK καθιστά δύσκολη τη συγγραφή του λάθους: το resolveScope(identity, options) δεν έχει καθόλου παράμετρο οργανισμού. Ο οργανισμός βρίσκεται μέσα στο identity, και μόνο ένα επαληθευμένο διακριτικό (token) παράγει κάτι τέτοιο. Δεν υπάρχει τίποτα μέσω του οποίου να περάσετε ένα αναγνωριστικό.
Γι' αυτόν τον λόγο ένα σώμα αιτήματος που κατονομάζει τον μισθωτή απορρίπτεται αντί να αγνοηθεί. Ο φρουρός απορρίπτει οποιοδήποτε από τα πέντε ονόματα πεδίων: orgId, organizationId, organization_id, tenant και tenantId. Ένα πεδίο που αγνοείται σιωπηρά μαθαίνει στον καλούντα ότι το πεδίο λειτουργεί. Ο πρώτος καλών το δοκιμάζει και βλέπει τα δικά του δεδομένα· ο δεύτερος στέλνει το αναγνωριστικό ενός άλλου οργανισμού. Η απόρριψη στο πρώτο αίτημα ξεκαθαρίζει τη σύμβαση πριν οποιοσδήποτε βασιστεί στη λάθος εκδοχή. Ο ίδιος κανόνας ισχύει και για το inputParams μιας αποστολής: η είσοδος μιας δεξιότητας που φέρει αναγνωριστικό οργανισμού απορρίπτεται κατά την αποστολή.
Ο άξονας της μονάδας είτε δηλώνεται και επιβάλλεται είτε δεν χρησιμοποιείται. Μια διαδρομή που δηλώνει needsUnit: true απορρίπτει το αίτημα όταν το διαπιστευτήριο δεν επιλύει κάποια μονάδα, με το unit να κατονομάζεται στο missing[]. Μην συνθέτετε μια μονάδα από έναν υποτομέα (subdomain) ή μια κεφαλίδα, και μην ορίζετε κάποια ως προεπιλογή. Μια επινοημένη μονάδα οριοθετεί διαφορετικά από τις πραγματικές μονάδες του οργανισμού και ενώνει εγγραφές που δεν θα έπρεπε.
Μια επιφάνεια που δεν μπορεί να εκφράσει το κατηγόρημα (predicate) αρνείται την εκτέλεση
Εάν μια διαδρομή δεν μπορεί να προσδιορίσει σε ποιον μισθωτή και κάτοχο ανήκει μια εγγραφή, καθώς και σε ποια μονάδα όταν απαιτείται, απορρίπτει το αίτημα. Δεν υπάρχει ανάγνωση σε επίπεδο ολόκληρου του οργανισμού ως εφεδρική λύση (fallback) ούτε τιμή κράτησης θέσης (placeholder). Μια τιμή κράτησης θέσης είναι η χειρότερη επιλογή, επειδή αποτελεί τιμή και οι τιμές αντιστοιχίζονται με εγγραφές: ένας δρομολογητής εργαλείων (tool router) που όριζε ως προεπιλογή τόσο για τον μισθωτή όσο και για τον χρήστη τη συμβολοσειρά 'unknown' σέρβιρε δεδομένα ολόκληρου του οργανισμού σε οποιονδήποτε τον καλούσε. Σε ένα όριο μισθωτή, το ?? 'unknown' αποτελεί ελάττωμα.
Η απόρριψη έχει μία μορφή παντού στην πλατφόρμα και μεταφέρει αρκετά στοιχεία ώστε ένας πελάτης να αποδώσει τη διόρθωση:
{
"error": true,
"code": "SCOPE_PREDICATE_MISSING",
"message": "Request cannot be scoped to a tenant from the presented credential.",
"resolved": ["tenant", "owner"],
"missing": ["unit"],
"troubleshooting": [
"The credential resolved tenant+owner; this route additionally requires a business unit.",
"Select a business unit in the client and retry — re-authentication will not change this outcome."
]
}Το error είναι πάντα true. Το code προέρχεται από τον κατάλογο κωδικών της πλατφόρμας. Το resolved[] κατονομάζει τους άξονες που προέκυψαν και το missing[] εκείνους που χρειαζόταν η διαδρομή αλλά δεν μπόρεσε να λάβει. Το troubleshooting[] αναφέρει τι θα έλυνε πραγματικά το πρόβλημα. Ένα απλό «forbidden» δεν μαθαίνει τίποτα σε κανέναν.
Διαχωρίστε τα 401 και 403, επειδή οι πελάτες ενεργούν διαφορετικά σε αυτά.
| Κατάσταση | Σημασία | Τι κάνει ο πελάτης |
|---|---|---|
| 401 | Μη αυθεντικοποιημένο | Συνδέεται ξανά |
| 403 | Αυθεντικοποιημένο, αλλά το αίτημα δεν μπορεί να οριοθετηθεί ή ο καλών δεν έχει το δικαίωμα | Σταματά τις επαναλήψεις και αλλάζει το αίτημα |
Μια απόρριψη εμβέλειας που απαντάται ως 401 στέλνει τον πελάτη σε έναν βρόχο σύνδεσης που καμία σύνδεση δεν μπορεί να τερματίσει: απορρίπτει τη συνεδρία και συνδέεται ξανά, προσπαθεί εκ νέου και λαμβάνει πάλι 401, ενώ ο χρήστης βλέπει επ' αόριστον μια ένδειξη φόρτωσης.
Δύο ακόμη μηχανισμοί καθιστούν την απόρριψη απόλυτη. Μέσα σε έναν χειριστή, το scopeOf(req) είναι ο μόνος τρόπος ανάγνωσης της εμβέλειας, και προκαλεί εξαίρεση (throws) αν ο φρουρός δεν εκτελέστηκε. Και ο φρουρός εκτελείται μετά την ανάλυση του σώματος (body parsing) και πριν από οποιονδήποτε χειριστή· ένας χειριστής που γίνεται προσβάσιμος χωρίς το κατηγόρημα (predicate) απαντά με 500 και MIDDLEWARE_ORDERING_ERROR, σκόπιμα, ώστε να καταλήξει στον προϋπολογισμό σφαλμάτων σας (error budget) αντί σε μια αναφορά συμβάντος.
Η βάση δεδομένων τηρεί την ίδια γραμμή από μόνη της
Ο φράκτης κώδικα και ο φράκτης βάσης δεδομένων είναι δύο μηχανισμοί για έναν νόμο, και λαμβάνετε και τους δύο.
Κάθε εντολή (statement) σε έναν οριοθετημένο πίνακα συνθέτει το tenantFence(scope) από το SDK· δεν γράφετε ποτέ το κατηγόρημα χειροκίνητα. Κάθε εντολή εκτελείται επίσης μέσα στο withScopedTx, το οποίο δεσμεύει τους τρεις άξονες για εκείνη τη μία συναλλαγή μέσω μιας ενιαίας συνάρτησης βάσης δεδομένων και απορρίπτει μια δεύτερη δέσμευση (SCOPE_ALREADY_BOUND). Από κάτω, κάθε πίνακας στο σχήμα σας (schema) έχει επιβεβλημένη την ασφάλεια επιπέδου εγγραφής (row-level security), και ο ρόλος με τον οποίο συνδέεται η διαδρομή του αιτήματός σας δεν μπορεί να αλλάξει ο ίδιος τον δεσμευμένο μισθωτή. Μια διεργασία που συνδέεται με ρόλο ικανό να παρακάμψει την ασφάλεια επιπέδου εγγραφής αρνείται να εκκινήσει με DB_ROLE_BYPASSES_ISOLATION. Το Κεφάλαιο 2.22, Το περιβάλλον εκτέλεσης προσθέτων (The plugin runtime), δείχνει τον κώδικα· το κεφάλαιο 2.21, Το Plugin SDK, δείχνει πώς αποδίδονται οι ρόλοι για εσάς.
Η μοναδική διέλευση: μια καταγεγραμμένη παραχώρηση
Υπάρχει ακριβώς ένας τρόπος να διασχίσετε το όριο του μισθωτή. Ο οργανισμός που κατέχει τις εγγραφές καταχωρεί μια παραχώρηση που κατονομάζει ποιος οργανισμός επιτρέπεται να διαβάσει ποιους πίνακες, υπό ποια συμφωνία και για πόσο διάστημα. Η βάση δεδομένων καθιστά την ανάγνωση αποκλειστικά για ανάγνωση (read-only), και κάθε προβολή καταγράφεται πριν από την ανάγνωση, και στους δύο οργανισμούς, μόνο με το αναγνωριστικό. Οι εγγραφές (writes) δεν διασχίζουν ποτέ το όριο· η εργασία που ανατίθεται σε άλλη εταιρεία ταξιδεύει ως μήνυμα. Οι ρόλοι του κατόχου και του διαχειριστή δεν διαβάζουν ποτέ πέρα από το όριο, και το αρχείο δήλωσης απορρίπτεται αν το δικαίωμα που επιτρέπει ανάγνωση μεταξύ οργανισμών δεν τους αποκλείει. Ένα πρόσθετο που αναζητά άλλον τρόπο διέλευσης δεν τον αποκτά.
Κανόνας 2: όλη η υπολογιστική επεξεργασία εκτελείται μέσω αποστολής UNO
Το UNO, η μηχανή ροής εργασιών, είναι η μόνη διαδρομή υπολογιστικής επεξεργασίας. Ο κώδικάς σας δεν καλεί ποτέ απευθείας έναν πάροχο μοντέλου ή μια μηχανή, ούτε μια ουρά (queue) ή έναν κεντρικό υπολογιστή ροής εργασιών (workflow host). Στέλνετε έναν φάκελο (envelope) στο τελικό σημείο αποστολής (dispatch endpoint) και λαμβάνετε πίσω 202 με αναγνωριστικά· το αποτέλεσμα φτάνει μέσω περιοδικού ελέγχου (polling) ή επανάκλησης (callback).
Ακολουθούν τρεις πρακτικές, και το πρότυπο τις διαθέτει ήδη και τις τρεις.
- Ένα αρχείο κατέχει το URL αποστολής. Το
UNO_DISPATCH_URLδιαβάζεται μία φορά στον φορτωτή ρυθμίσεων (config loader) και πρέπει να είναι διεύθυνση εντός συστάδας (in-cluster). Μια δημόσια διεύθυνση απορρίπτεται κατά την εκκίνηση, επειδή τίποτα δεν εξέρχεται από την εγκατάσταση. - Μία κλειστή λίστα επιτρεπομένων (allow-list) για το τι μπορεί να αποστείλει αυτή η επιφάνεια. Ένα σύστημα υποστήριξης (backend) που αποστέλλει οποιοδήποτε αναγνωριστικό δεξιότητας του παραδώσει ένα πρόγραμμα περιήγησης αποτελεί έναν ενδιάμεσο διακομιστή (proxy) γενικής χρήσης για κάθε δεξιότητα στο μητρώο, συμπεριλαμβανομένων δεξιοτήτων άλλων προσθέτων και δεξιοτήτων που ξοδεύουν τον προϋπολογισμό μοντέλων κάποιου άλλου. Η λίστα είναι μια σταθερά επιπέδου ενότητας (module-level constant) με τύπους εργασιών εντός χώρου ονομάτων (namespaced), ποτέ μια μεταβλητή περιβάλλοντος. Ένα αναγνωριστικό που δεν βρίσκεται σε αυτήν απορρίπτεται με
SKILL_NOT_ALLOWED. - Επανελέγξτε ό,τι επιστρέφει. Όταν αναγιγνώσκετε ξανά μια εργασία, ο πελάτης του SDK συγκρίνει το
organization_idτης επιστρεφόμενης εγγραφής με τον μισθωτή του καλούντος στη δική σας πλευρά της κλήσης δικτύου. Ένας φράκτης που υπάρχει μόνο στην άλλη πλευρά μιας κλήσης είναι απλώς μια σύμβαση.
Κανόνας 3: όλο το AI περνά μέσα από τον Δρομολογητή Παρόχων AI
Ένα πρόσθετο δεν πραγματοποιεί καμία κλήση σε μοντέλο, πουθενά. Δεν υπάρχει SDK παρόχου στο package.json, κανένα κλειδί μοντέλου στο περιβάλλον και κανένας αναμεταδότης (relay). Μόνο ο δρομολογητής (router) κατέχει τα διαπιστευτήρια παρόχου του οργανισμού και λαμβάνει την τελική απόφαση για τον πάροχο και το μοντέλο.
Αυτό που μπορεί να κάνει ένα πρόσθετο είναι να εκφράσει προτιμήσεις, κατά τον χρόνο εγγραφής, στην εγγραφή μητρώου της δεξιότητας του αρχείου δήλωσης:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}Ο δρομολογητής ικανοποιεί μια προτίμηση μόνο όταν ο οργανισμός έχει ενεργοποιήσει και πιστοποιήσει τον συγκεκριμένο πάροχο. Διαφορετικά, τον υποκαθιστά από τη δεξαμενή του ίδιου του οργανισμού. Το capabilityProfile δεν επιλέγει ποτέ· φιλτράρει, και το πεδίο του dataResidency είναι ένας αυστηρός περιορισμός δικαιοδοσίας τον οποίο ο δρομολογητής είτε ικανοποιεί είτε απορρίπτει. Η παράλειψη όλων αυτών είναι η σωστή προεπιλογή για τις περισσότερες δεξιότητες: οι αναθέσεις ρόλων του ίδιου του οργανισμού αποφασίζουν τότε, άλλωστε ο οργανισμός είναι αυτός που πληρώνει.
Επιστρέφονται δύο είδη απόρριψης, και σημαίνουν πολύ διαφορετικά πράγματα.
| Κωδικός | Κατάσταση | Τι σημαίνει |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | Ο κώδικάς σας προσπάθησε να καλέσει τον ίδιο τον δρομολογητή. Σταματήστε: αυτό είναι το όριο διασύνδεσης (seam) που απορρίπτει εκ σχεδιασμού, και δεν επιδέχεται επανάληψη |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Κανένας ενεργοποιημένος πάροχος δεν διαθέτει μοντέλο που να ικανοποιεί το προφίλ. Χαλαρώστε το προφίλ, ή ο οργανισμός ενεργοποιεί έναν ικανό πάροχο |
NO_PROVIDER_FOR_ROLE |
422 | Ο οργανισμός δεν έχει ρυθμίσει τη δρομολόγηση για αυτόν τον ρόλο. Εμφανίστε το κείμενο αποκατάστασης του δρομολογητή στον χρήστη |
Το δεύτερο ζεύγος ανήκει στην οθόνη, όχι σε αρχείο καταγραφής (log). Δεν υπάρχει προεπιλεγμένο μοντέλο ούτε εφεδρικός πάροχος: ένας ρόλος που δεν έχει ρυθμίσει ο οργανισμός αποτυγχάνει εμφανώς, με μια πρόταση που αναφέρει τι πρέπει να ρυθμιστεί.
Η μόνη ανάγνωση που μπορεί να κάνει ένα πρόσθετο από τον δρομολογητή είναι το effectiveRoute() από το runtime/ai-route. Απαντά ποιον πάροχο και ποιο μοντέλο θα επέλεγε ο δρομολογητής για τον συνδεδεμένο οργανισμό χωρίς να στείλει αίτημα AI, και επιστρέφει την απόρριψη του δρομολογητή ολογράφως όταν δεν υπάρχει μοντέλο. Το Κεφάλαιο 2.22, Το περιβάλλον εκτέλεσης προσθέτων, το παρουσιάζει.
Η κλίμακα εμπιστοσύνης (trust ladder) προσθέτει μία ακόμη γραμμή. Μόνο τα πρόσθετα core και verified μπορούν να δηλώσουν τις δύο βαθμίδες δεξιοτήτων του αρχείου δήλωσης που φτάνουν στον δρομολογητή, tool_using και llm_only. Όλοι οι υπόλοιποι διαμεσολαβούν σε ντετερμινιστικές εργασίες και αφήνουν την πλατφόρμα να αναλάβει το μέρος της επικοινωνίας με το μοντέλο.
Κανόνας 4: τα κλειδιά ανήκουν στον οργανισμό
Κάθε οργανισμός φέρνει τον δικό του λογαριασμό και το δικό του κλειδί παρόχου, και πληρώνει τον δικό του λογαριασμό. Το κλειδί βρίσκεται στη δεξαμενή παρόχων AI του οργανισμού, την οποία διαχειρίζονται οι δικοί του διαχειριστές από την κονσόλα, και ο δρομολογητής το επιλύει κατά τον χρόνο της κλήσης. Δεν υπάρχει κοινόχρηστο κλειδί πλατφόρμας πίσω από έναν μισθωτή, επομένως κανένας οργανισμός δεν ξοδεύει τον προϋπολογισμό κάποιου άλλου.
Για μια επέκταση αυτό σημαίνει τρία πράγματα.
- Δεν κατέχετε ποτέ κλειδί μοντέλου, είτε στον κώδικα είτε στις ρυθμίσεις είτε σε χώρο αποθήκευσης μυστικών (secret store). Η πύλη ελέγχου
no-credentialsπροκαλεί αποτυχία της μεταγλώττισης (build) αν κάποιο κλειδί είναι αναγνώσιμο, και ο φορτωτής ρυθμίσεων αρνείται να εκκινήσει αν υπάρχει κάποιο. - Δεν απαριθμείτε ποτέ τα κλειδιά ενός οργανισμού. Αν το πρόσθετό σας θεωρεί ότι χρειάζεται να το κάνει, η απαίτηση βρίσκεται σε λάθος μέρος.
- Ένας οργανισμός χωρίς κλειδί δεν λαμβάνει απαντήσεις AI. Αυτή είναι μια αναμενόμενη κατάσταση με πραγματική οθόνη. Κατονομάστε τον ρόλο που λείπει και παραθέστε την ενέργεια αποκατάστασης, και στη συνέχεια κατευθύνετε τον χρήστη στις ρυθμίσεις παρόχου του. Μην το αποδίδετε ως κενό αποτέλεσμα.
Κανόνας 5: οι αδειοδοτημένες δυνατότητες ελέγχονται έναντι της άδειας χρήσης
Το τι μπορεί να χρησιμοποιήσει μια εγκατάσταση πέρα από το βασικό επίπεδο Community προέρχεται από ένα μέρος: το έγγραφο άδειας χρήσης που υπογράφει η Adverant, το οποίο επαληθεύεται στην εγκατάσταση μόνο με δημόσια κλειδιά. Η επέκτασή σας δεν αποφασίζει ποτέ βασιζόμενη σε κάτι ασθενέστερο, όπως ένα όνομα πλάνου σε ένα διακριτικό ή μια σημαία (flag) στις ρυθμίσεις.
Σε ένα πρόσθετο, ο απλούστερος τρόπος για να συνδέσετε μια λειτουργία με την άδεια χρήσης είναι πάνω στο δικαίωμα που την προστατεύει. Ένα δικαίωμα στο μητρώο rights του αρχείου δήλωσης μπορεί να κατονομάσει μια λειτουργία licence:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Όποιος καλεί μια διαδρομή που προστατεύεται από αυτό το δικαίωμα απορρίπτεται με LICENCE_LOCKED (403), ανεξαρτήτως των ρόλων και των θέσεων (seats) που κατέχει, όταν η άδεια χρήσης του οργανισμού δεν περιλαμβάνει το compliance-packs. Η απόρριψη κατονομάζει τη λειτουργία και τι την περιλαμβάνει, και αναφέρει ποιος μπορεί να την ενεργοποιήσει.
Η κατάσταση της άδειας χρήσης έχει επίσης σημασία. Ενώ μια άδεια χρήσης είναι έγκυρη ή βρίσκεται στο παράθυρο προειδοποίησής της, οι αδειοδοτημένες λειτουργίες εκτελούνται κανονικά, και συνεχίζουν να εκτελούνται κατά την περίοδο χάριτος, όπου η περίοδος χάριτος εμφανίζει την ειδοποίηση LICENCE_IN_GRACE. Μόλις μια άδεια χρήσης ξεπεράσει την περίοδο χάριτος, επιβάλλει περιορισμούς: οι τρέχουσες εργασίες και οι αναγνώσεις συνεχίζονται, όπως και οι εξαγωγές και οι ενημερώσεις ασφαλείας, αλλά η δημιουργία οτιδήποτε νέου υπό μια αδειοδοτημένη λειτουργία απορρίπτεται με LICENCE_LOCKED. Κατασκευάστε τις διαδρομές δημιουργίας σας αναμένοντας αυτή την απάντηση.
Όταν το πρόσθετό σας ρωτά τον έλεγχο δικαιωμάτων (entitlement check) αν ένας οργανισμός κατέχει μια λειτουργία, λαμβάνει μια ετυμηγορία, ποτέ μια απλή λογική τιμή (boolean). Το «μη προσβάσιμο» και το «προσβάσιμο και όχι» είναι διαφορετικά γεγονότα με διαφορετικούς κωδικούς: ENTITLEMENT_UNREACHABLE (502) και ENTITLEMENT_DENIED (403). Μια στιγμιαία διακοπή προσβασιμότητας δεν πρέπει ποτέ να υποβαθμίζει σιωπηρά κάθε πελάτη στο δωρεάν βασικό επίπεδο.
MANIFEST_SCOPE_WIDENED μέχρι να συμφωνήσουν δύο αξιολογητές και ο υπεύθυνος συμμόρφωσης.Το manifest επαναδιατυπώνει τον κανόνα
Κάθε αρχείο δήλωσης v2 φέρει μια ενότητα architecture με τρεις υποχρεωτικές προτάσεις, και ο επικυρωτής (validator) κλειδώνει τη διατύπωσή τους. Σε ένα πρόσθετο που κατασκευάζετε για τη δική σας εγκατάσταση έχουν ως εξής:
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}Αυτές οι προτάσεις ελέγχονται. Ένα πρόσθετο του οποίου το αρχείο δήλωσης συμφωνούσε με τους κανόνες ενώ ο κώδικάς του καλούσε απευθείας έναν πάροχο μοντέλου θα ψευδόταν μέσα στη δική του σύμβαση, και οι πύλες ελέγχου υπάρχουν για να καθιστούν το ψέμα ανιχνεύσιμο.
Οι πύλες που επιβάλλουν κάθε κανόνα
Το SDK διαθέτει είκοσι δύο πύλες ελέγχου συμμόρφωσης ως μία εντολή, την nexus-gates. Το Κεφάλαιο 2.21, Το Plugin SDK, περιγράφει την καθεμία. Εδώ ομαδοποιούνται ανάλογα με τον κανόνα που επιβάλλουν.
| Κανόνας | Πύλες ελέγχου | Τι προκαλεί την αποτυχία της κατασκευής (build) |
|---|---|---|
| Απομόνωση στο επίπεδο διαδρομών | scope-adherence, one-fence, rights-register, crud-adherence |
Μια διαδρομή /api χωρίς τον φρουρό εμβέλειας, ένα δεύτερο χειροκίνητο κατηγόρημα μισθωτή, μια διαδρομή εμβέλειας χωρίς δικαίωμα, μια διαδρομή μεταβολής (mutating route) της οποίας το δικαίωμα δεν κατονομάζει τίποτα |
| Απομόνωση στην SQL | sql-fence, no-set-config |
Μια εντολή σε οριοθετημένο πίνακα χωρίς τον φράκτη· κώδικας προσθέτου που δεσμεύει ο ίδιος τη ρύθμιση του μισθωτή |
| Απομόνωση στη βάση δεδομένων | migrations-are-scoped, rls-present, db-role-honest |
Ένας πίνακας από τον οποίο λείπει ένας άξονας ή ένα κλειδί με προπορευόμενο τον μισθωτή, ένας πίνακας χωρίς επιβεβλημένη ασφάλεια επιπέδου εγγραφής, μια διαδρομή αιτήματος που συνδέεται ως κάτοχος ή υπερχρήστης (superuser) |
| Η μοναδική διέλευση | grants-declared |
Ένας πίνακας με παραχώρηση στις μετεγκαταστάσεις (migrations) τον οποίο δεν δηλώνει το αρχείο δήλωσης, ή μια θέση ανάγνωσης στην οποία δόθηκαν προνόμια χειροκίνητα |
| Υπολογιστική επεξεργασία μέσω του UNO | no-direct-compute |
Μια απευθείας κλήση (fetch) σε πάροχο μοντέλου ή μηχανή, ή σε ουρά ή κεντρικό υπολογιστή ροής εργασιών· ένας δεύτερος αναγνώστης του URL αποστολής |
| AI και κλειδιά | no-credentials |
Ένα διαπιστευτήριο παρόχου μοντέλου αναγνώσιμο στο αποθετήριο ή στο περιβάλλον |
| Η δηλωμένη σύμβαση | api-contract, platform-clients, declared-input |
Μια διαδρομή εγγεγραμμένη αλλά μη δηλωμένη, ή δηλωμένη αλλά μη εγγεγραμμένη· ένας πελάτης πλατφόρμας που έχει εισαχθεί (imported) αλλά δεν έχει κατονομαστεί |
Κάθε πύλη ελέγχου διαθέτει έναν αυτοέλεγχο (self-test) που αποδεικνύει ότι αποτυγχάνει σε ένα εξάρτημα δοκιμής (fixture) κατασκευασμένο για να την ενεργοποιήσει. Το npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test τις εκτελεί όλες, και μια πύλη ελέγχου που έχει σταματήσει να αποτυγχάνει στο δικό της εξάρτημα δοκιμής έχει σταματήσει να λειτουργεί.
Πριν ζητήσετε αξιολόγηση
Αυτή είναι η λίστα που διατρέχω πριν ζητήσω από έναν συνάδελφο να αξιολογήσει ένα πρόσθετο. Κάθε γραμμή είναι κάτι που ένας αξιολογητής στην Corrán Orbital μου έχει επιστρέψει τουλάχιστον μία φορά.
- Κάθε διαδρομή
/apiκαταχωρεί τον φρουρό εμβέλειας, και οι μόνες ανώνυμες διαδρομές είναι ακριβείς διαδρομές που δηλώνονται ωςauth: publicμεallowAnonymous: true. - Κάθε διαδρομή που εξυπηρετεί ο φρουρός εμβέλειας κατονομάζει ένα
rightαπό το μητρώο του αρχείου δήλωσης, και κανένας χειριστής δεν φέρει δικό του έλεγχο δικαιωμάτων. - Κανένας χειριστής δεν διαβάζει οργανισμό, άτομο ή μονάδα από το σώμα του αιτήματος, το ερώτημα ή μια κεφαλίδα.
- Κάθε εντολή σε έναν οριοθετημένο πίνακα διέρχεται από το
tenantFenceμέσα στοwithScopedTx, και τίποτα στο αποθετήριο δεν καλεί τοset_config. - Κάθε πίνακας διαθέτει τις τρεις στήλες αξόνων, ένα πρωτεύον κλειδί που ξεκινά με το
organization_id, και σύνθετα ξένα κλειδιά που μεταφέρουν τον μισθωτή. - Το URL αποστολής διαβάζεται σε ένα αρχείο, και η λίστα επιτρεπομένων αποστολής είναι μια σταθερά τύπων εργασιών εντός χώρου ονομάτων.
- Τίποτα στο
package.jsonδεν επικοινωνεί με πάροχο μοντέλου, και κανένα κλειδί δεν βρίσκεται στο περιβάλλον. - Κάθε λειτουργία που περιλαμβάνεται μόνο σε ορισμένες άδειες χρήσης κατονομάζει το
licenceτης πάνω στο δικαίωμα που την προστατεύει. - Το
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testείναι πράσινο, το ίδιο και τοnpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.
Αν ισχύουν και τα εννέα, η αξιολόγηση αφορά το προϊόν σας, εκεί δηλαδή όπου θα έπρεπε να αφιερώνεται ο χρόνος ενός αξιολογητή.
Γιατί η πλατφόρμα επιβάλλει αυτούς τους κανόνες
Κάθε παραπάνω κανόνας υπήρξε κάποτε μια σύμβαση κάπου, και κάθε σύμβαση απέτυχε με τον ίδιο τρόπο: οι διαδρομές που τη θυμήθηκαν ήταν εντάξει και η μία που την ξέχασε αποτέλεσε το συμβάν ασφαλείας. Ένας φράκτης επιχειρηματικής μονάδας που εφαρμόστηκε ως προαιρετικό ενδιάμεσο λογισμικό (middleware) παρακάμφθηκε με έξι ανεξάρτητους τρόπους, καθένας εκ των οποίων ήταν μια διαδρομή που δεν συμμετείχε ποτέ. Μια μεταβλητή περιβάλλοντος που ξαναέγραφε την ταυτότητα του μισθωτή σέρβιρε σε έναν οργανισμό τις 1.406 επαφές ενός άλλου, και φαινόταν σωστή κατά την αξιολόγηση επειδή ήταν σωστή για το pod για το οποίο γράφτηκε.
Έτσι, η πλατφόρμα τοποθετεί το κατηγόρημα εκεί από όπου διέρχεται ήδη κάθε επιφάνεια: στον φρουρό εμβέλειας και στη συνάρτηση φράκτη, στον περιτυλιγμένο κώδικα συναλλαγής (transaction wrapper) και στην επιβεβλημένη ασφάλεια επιπέδου εγγραφής, καθώς και στον πελάτη αποστολής. Στη συνέχεια, μια πύλη ελέγχου απαριθμεί κάθε διαδρομή, κάθε εντολή και κάθε εισαγωγή (import), και προκαλεί αποτυχία της έκδοσης δόμησης (build) όταν μία από αυτές προσεγγίζει έναν οριοθετημένο πίνακα, ένα μοντέλο ή μια μηχανή υπολογιστικής επεξεργασίας χωρίς να διέλθει από αυτούς τους μηχανισμούς. Το κόστος αυτού του σχεδιασμού είναι ότι το πρώτο σας πρόσθετο δίνει την αίσθηση περιορισμού. Το όφελος είναι ότι το χιλιοστό πρόσθετο είναι απομονωμένο χωρίς ο δημιουργός του να γνωρίζει καν ότι υπάρχει η λειτουργία, επειδή δεν υπάρχει άλλη διαδρομή προς τα δεδομένα την οποία να μπορεί να ακολουθήσει.
Υπάρχει ένα ειλικρινές όριο σε όλα αυτά. Οι πύλες ελέγχου αποδεικνύουν ότι ο κώδικάς σας διέρχεται από τους μηχανισμούς· δεν μπορούν να αποδείξουν ότι η λογική του προϊόντος σας είναι σωστή. Μια διαδρομή που οριοθετεί σωστά ένα ερώτημα στις εγγραφές του κατόχου μπορεί ακόμα να εμφανίσει τις λάθος εγγραφές στον σωστό κάτοχο. Το κιτ δοκιμών απομόνωσης στο κεφάλαιο 2.22, Το περιβάλλον εκτέλεσης προσθέτων, επιτίθεται σε κάθε διαδρομή ως άλλος οργανισμός και ως συνάδελφος, αφαιρώντας κάθε φράκτη με τη σειρά, και αυτή είναι η δοκιμή που θα εκτελούσα πριν εμπιστευτώ τη δική μου ανάγνωση για οτιδήποτε από αυτά.

