ΣύνδεσηΚλείστε μια ενημέρωση

Κεφάλαιο 2.22

Το περιβάλλον εκτέλεσης προσθέτων (plugin runtime)

Οι λειτουργικές μονάδες του SDK (κιτ ανάπτυξης λογισμικού) στις οποίες βασίζεται η εκτέλεση του προσθέτου σας, από τον φύλακα εμβέλειας (scope guard) και τον φράχτη της βάσης δεδομένων έως την αποστολή UNO, την ανάγνωση διαδρομής AI (τεχνητής νοημοσύνης) και τους ελέγχους αδειών χρήσης. Στη συνέχεια, δοκιμές σε πραγματική βάση δεδομένων, καταχώριση των δεξιοτήτων σας και ενσωμάτωση (onboarding).

Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

21 λεπτά ανάγνωσης

Το τμήμα χρόνου εκτέλεσης του SDK (κιτ ανάπτυξης λογισμικού) είναι ένα σύνολο λειτουργικών μονάδων κάτω από το @adverant-nexus/plugin-sdk/runtime/*, καθώς και βοηθητικά εργαλεία δοκιμών κάτω από το testing/*. Τα εισάγετε· δεν τα υλοποιείτε ξανά. Αυτή είναι όλη η ιδέα, και χρειάστηκε μία απορριφθείσα αξιολόγηση για να την πάρω στα σοβαρά: η σημείωση του αξιολογητή για τον χειρόγραφο έλεγχο εμβέλειας του πρώτου μου πρόσθετου ήταν μία μόνο γραμμή: «το SDK το έχει ήδη αυτό, και το δικό σας δέχεται ένα token πρόκλησης MFA (ταυτοποίησης πολλαπλών παραγόντων) ως συνεδρία».

Το κεφάλαιο αυτό ακολουθεί ένα αίτημα μέσα από ένα πρόσθετο σε λειτουργία, όπως το συνδέει το πρότυπο πλήρους υπηρεσίας: τον φύλακα εμβέλειας, τον φράκτη της βάσης δεδομένων, τη μία επιτρεπόμενη διέλευση, την αποστολή μέσω του UNO, την ανάγνωση της διαδρομής AI (τεχνητής νοημοσύνης) και τους ελέγχους άδειας χρήσης. Στη συνέχεια καλύπτει τις δοκιμές, την καταχώριση των δεξιοτήτων του manifest σας και τα βήματα ένταξης.

Εμβέλεια: ένας φύλακας ανά πλαίσιο εργασίας (framework)

Κάθε διαδρομή /api φέρει τον φύλακα εμβέλειας. Επαληθεύει το bearer token, επιλύει από αυτό τους τρεις άξονες (tenant, κάτοχος, μονάδα), απορρίπτει ένα σώμα αιτήματος που κατονομάζει tenant, εφαρμόζει το δικαίωμα της διαδρομής από το μητρώο του manifest και μόνο τότε επιτρέπει την εκτέλεση του handler. Το SDK παρέχει έναν προσαρμογέα ανά framework, όλους από το @adverant-nexus/plugin-sdk/runtime/scope και όλους με τις ίδιες επιλογές.

Framework Προσαρμογέας
Express scopeMiddleware
Fastify requireScope, ως preHandler
Next withScope, που περιβάλλει τον handler· ένας handler του Next δεν γνωρίζει τη διαδρομή του, οπότε το withScope τη λαμβάνει ως τρίτο όρισμα

Ακολουθεί η σύνδεση Express του προτύπου, συντομευμένη. Ο επαληθευτής είναι του SDK και δεσμεύει το token στη μορφή συνεδρίας της υπηρεσίας ταυτότητας: μόνο HS256· υποχρεωτικά τα iss, exp, iat και jti· διάρκεια ζωής το πολύ μία ώρα· και κανένα token πρόκλησης MFA, πλαστοπροσωπίας ή πόρου OAuth (του ανοιχτού προτύπου για εξουσιοδότηση μέσω αντιπροσώπου) δεν γίνεται δεκτό ως συνεδρία.

import { platformAccessTokenVerifier } from "@adverant-nexus/plugin-sdk/runtime/platform-token";
import { scopeMiddleware } from "@adverant-nexus/plugin-sdk/runtime/scope";

const requireScope = scopeMiddleware({
  verify: platformAccessTokenVerifier(config.PLATFORM_JWT_SECRET),
  rights: { manifest },
});

router.get("/api/projects", requireScope, async (req, res) => {
  res.json({ projects: await db.listProjects(scopeOf(req)) });
});

Ο φύλακας δικαιωμάτων εφαρμόζει το δικαίωμα μιας διαδρομής σε τέσσερα βήματα. Ένας ρόλος στη λίστα never του δικαιώματος απορρίπτει με AUTHORITY_EXCEEDED και τη διατύπωση barred, και καμία θέση δεν το αναιρεί. Ένας ρόλος στο roles επιτρέπει την πρόσβαση, με επιπλέον ενεργή θέση όταν το δικαίωμα ορίζει seat: true. Διαφορετικά, επιτρέπει την πρόσβαση μια ενεργή θέση που φέρει το δικαίωμα. Διαφορετικά, το αίτημα απορρίπτεται AUTHORITY_EXCEEDED, με κατονομασία των προσώπων που θα μπορούσαν να παραχωρήσουν θέση. Δώστε στον φύλακα έναν χώρο αποθήκευσης (rights: { manifest, store: { pool, schema } }) και διαβάζει τις θέσεις υπό την εμβέλεια του ίδιου του καλούντος· ένα δικαίωμα που κατονομάζει licence χρειάζεται επίσης αναγνώστη άδειας χρήσης, όπως περιγράφεται παρακάτω.

Μέσα σε έναν handler, το scopeOf(req) είναι ο μόνος τρόπος ανάγνωσης της επιλυμένης εμβέλειας, και προκαλεί εξαίρεση αν ο φύλακας δεν εκτελέστηκε. Ένας φύλακας καταχωρισμένος σε πρόθεμα, που εκτελείται πριν ταιριάξει οποιαδήποτε διαδρομή, απαντά 500 MIDDLEWARE_ORDERING_ERROR· μια διαδρομή που καταχωρίζει ο κώδικάς σας χωρίς να τη δηλώνει το manifest απαντά 500 UNHANDLED_ERROR. Και οι δύο αποτυγχάνουν με κλείσιμο.

Οι διαδρομές /internal του προτύπου, τις οποίες καλεί η πλατφόρμα, χρησιμοποιούν το άλλο καθεστώς. Ο φύλακας υπηρεσίας ελέγχει το X-Service-Key σε σταθερό χρόνο και λαμβάνει τον tenant από το X-Organization-ID της πλατφόρμας, απορρίπτοντας MISSING_SERVICE_KEY, INVALID_SERVICE_KEY ή MISSING_ORG_ID_HEADER. Για το υπογεγραμμένο token ανά κλήση της πλατφόρμας, το SDK διαθέτει το requireService (Fastify) και το serviceMiddleware (Express), τα οποία ελέγχουν επίσης για ποια δεξιότητα και διαδρομή εκδόθηκε το token και απορρίπτουν token που χρησιμοποιείται δύο φορές.

Ο φράκτης της βάσης δεδομένων: tenantFence και withScopedTx

Κάθε εντολή σε πίνακα με εμβέλεια συνθέτει τον φράκτη και εκτελείται μέσα σε συναλλαγή με εμβέλεια:

import { withScopedTx } from "@adverant-nexus/plugin-sdk/runtime/db";
import { tenantFence } from "@adverant-nexus/plugin-sdk/runtime/fence";

async function listProjects(scope: ResolvedScope) {
  // Projects are owner-private inside the organisation, so the owner axis is passed explicitly.
  const f = tenantFence(scope, { alias: "p", owner: scope.owner });
  const r = await withScopedTx(pool, scope, { schema: SCHEMA }, (db) =>
    db.query(`SELECT p.* FROM anomaly_review.reviews p WHERE ${f.where} ORDER BY p.created_at DESC`, f.params),
  );
  return r.rows;
}

Το tenantFence(scope, options) κατασκευάζει το κατηγόρημα και τις παραμέτρους του από μια επιλυμένη εμβέλεια. Περάστε owner για προσωπικούς πίνακες· παραλείψτε το για οργανωσιακά αντικείμενα όπου ο κάτοχος αποτελεί στοιχείο προέλευσης. Όταν η εντολή έχει ήδη παραμέτρους, το startIndex υποδεικνύει στον φράκτη από πού να ξεκινήσει την αρίθμηση. Μια εισαγωγή δεν λαμβάνει ποτέ τους άξονες ως είσοδο: γράφει τα scope.tenant, scope.owner και scope.unit από την εμβέλεια.

Το withScopedTx δεσμεύει και τους τρεις άξονες για μία συναλλαγή μέσω της μοναδικής συνάρτησης δέσμευσης του σχήματος και στη συνέχεια εκτελεί το callback σας. Μια δεύτερη δέσμευση στην ίδια συναλλαγή προκαλεί SCOPE_ALREADY_BOUND (500: ο κώδικάς σας δέσμευσε δύο φορές· ο καλών δεν έκανε τίποτα λάθος). Ένας απών ή μηδενικός tenant ή κάτοχος προκαλεί SCOPE_PREDICATE_INVALID (403). Η ρύθμιση είναι τοπική στη συναλλαγή, οπότε μια σύνδεση από pool δεν μπορεί να μεταφέρει έναν tenant στο επόμενο αίτημα.

Δύο αδελφές συναρτήσεις καλύπτουν τις περιπτώσεις που δεν αποτελούν αίτημα ενός προσώπου. Το withTenantScopedTx δεσμεύει tenant και μονάδα χωρίς κάτοχο, για γραμμές που διαβάζει μια μηχανή (το μητρώο συσκευών), και απορρίπτει εμβέλεια που φέρει κάτοχο. Το maintenanceScope(reason) υποχρεώνει μια λειτουργία σε επίπεδο οργανισμού να δηλώσει ρητά τι είναι πριν ανοίξει η συναλλαγή του κατόχου. Ο φράκτης του κώδικα και η υποχρεωτική ασφάλεια επιπέδου γραμμής είναι δύο μηχανισμοί για έναν κανόνα· ο έλεγχος εκκίνησης αρνείται να δεχτεί συνδέσεις έως ότου η βάση δεδομένων αποδείξει ότι ισχύει ο δεύτερος (διαφορετικά DB_ROLE_BYPASSES_ISOLATION).

Κάθε απόρριψη αποτελεί μια εγγραφή

Το πρότυπο εγκαθιστά ένα ακόμη middleware, μία φορά, ανάμεσα στον αναλυτή σώματος και στους routers: το βιβλίο καταγραφής αρνήσεων.

import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";

app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));

Περιβάλλει την απόκριση ώστε κάθε άρνηση που διαβάζει ένα πρόσωπο, είτε από τον φύλακα δικαιωμάτων είτε από έναν handler είτε από έναν χώρο αποθήκευσης, να γράφεται στον πίνακα refusal του σχήματός σας μέσα στη συναλλαγή με εμβέλεια του ίδιου του προσώπου πριν σταλεί το σώμα. Μια ανώνυμη απόκριση 401 δεν γράφει τίποτα. Αν η γραμμή δεν μπορεί να γραφτεί, η απάντηση γίνεται UNHANDLED_ERROR: ένα «όχι» που το προϊόν δεν μπορεί να καταγράψει δεν αποστέλλεται σαν να είχε καταγραφεί. Κατά την εκκίνηση εκτελείται το assertRefusalLedger για να ελεγχθεί ότι ο πίνακας μπορεί να δεχτεί τη γραμμή του βιβλίου, και ένας χώρος αποθήκευσης μπορεί να καλέσει το noteSubject({ recordId, isDemo }) ώστε κάθε άρνηση να κατονομάζει την εγγραφή στην οποία αφορούσε. Όταν ένας πελάτης ρωτήσει γιατί απορρίφθηκε κάποιος την περασμένη Τρίτη, η απάντηση είναι ένα ερώτημα, όχι μια εικασία.

Η μοναδική διέλευση: μια καταγεγραμμένη παραχώρηση μόνο για ανάγνωση

Όταν ένας από τους πελάτες σας εκτελεί εργασία για έναν άλλον και ο άλλος μπορεί να την επιθεωρήσει, υπάρχει ένας εγκεκριμένος τρόπος διέλευσης του ορίου. Ο οργανισμός που κατέχει τις γραμμές καταγράφει μια παραχώρηση. Ο οργανισμός του αναγνώστη επιτρέπει την πρόσβαση σε ένα πρόσωπο μέσω θέσης που φέρει το δικαίωμα granted.read, το οποίο πρέπει να κατονομάζει τα owner και admin στο never. Η ανάγνωση εκτελείται ως έκτος ρόλος βάσης δεδομένων, η θέση ανάγνωσης, η οποία μπορεί να επιλέγει μόνο τους πίνακες που απαριθμεί το databases[].granted:

const r = await withSeatTx({ app: appPool, seat: seatPool }, seatsOf(req), { holder, grantId }, { schema: "anomaly_review" }, (db) => {
  const f = grantFence(db.seat, { alias: "r" });
  return db.query(`SELECT r.review_id FROM anomaly_review.reviews r WHERE ${f.where}`, f.params);
});
if (!r.ok) return res.status(r.status).json(r.refusal);

Το withSeatTx γράφει πρώτα την καταγραφή προβολής στον tenant του ίδιου του αναγνώστη και στη συνέχεια δεσμεύει τη θέση ανάγνωσης στην παραχώρηση, γράφοντας την καταγραφή προβολής στον tenant του κατόχου. Η ίδια η πολιτική της βάσης δεδομένων ελέγχει ότι η παραχώρηση κατονομάζει τον οργανισμό του αναγνώστη, καλύπτει τον πίνακα, έχει ξεκινήσει, δεν έχει λήξει και δεν έχει ανακληθεί, και ότι η συγκεκριμένη συναλλαγή έγραψε την καταγραφή προβολής της. Μια ανάγνωση που παραλείπει την καταγραφή δεν βλέπει τίποτα. Κατά την εκκίνηση, το assertSeatAtBoot(seatPool, schema) ελέγχει ότι το pool που ανοίχτηκε από το seat.url είναι πράγματι η θέση και τίποτα περισσότερο, και διαφορετικά απορρίπτει με DB_SEAT_ROLE_INVALID.

Αποστολή μέσω UNO

Όλοι οι υπολογισμοί περνούν από έναν πελάτη, κατασκευασμένο σε ένα αρχείο, με κλειστή λίστα επιτρεπόμενων:

import { UnoClient } from "@adverant-nexus/plugin-sdk/runtime/uno";

/** The namespaced job types this surface may dispatch. Closed; edit in code. */
export const DISPATCHABLE = Object.freeze([`${manifest.name}.sentiment_score`] as const);

export function createUno(deps: UnoDeps): UnoClient {
  return new UnoClient({
    baseUrl: deps.dispatchUrl,
    serviceKey: deps.serviceKey,
    callerService: manifest.name,
    dispatchable: DISPATCHABLE,
  });
}

Η λίστα επιτρεπόμενων είναι σκόπιμα σταθερά σε επίπεδο λειτουργικής μονάδας. Αν ένας διαχειριστής μπορούσε να τη διευρύνει μέσω διαμόρφωσης, η διαδρομή θα γινόταν διακομιστής μεσολάβησης αποστολής για ολόκληρο το μητρώο. Η δοκιμή του ίδιου του προτύπου επιβεβαιώνει ότι η λίστα κατονομάζει ακριβώς τους τύπους εργασιών στους οποίους μεταγλωττίζεται το manifest.

Ο φάκελος

Μια αποστολή φέρει έξι πεδία στον υποχρεωτικό της πυρήνα. Ο πελάτης συμπληρώνει τον tenant και τον δρώντα από την επαληθευμένη εμβέλεια, ποτέ από το αίτημα:

Πεδίο Τι περιέχει
jobType Ο τύπος εργασίας με χώρο ονομάτων, <plugin name>.<skill id>
organizationId Ο tenant, από την εμβέλεια
userId Ο δρών, από την εμβέλεια, για έλεγχο και χρέωση
inputParams Η είσοδος της δεξιότητας. Δεν φέρει ποτέ αναγνωριστικό tenant· όποια φέρει απορρίπτεται κατά την αποστολή
priority critical, high, normal ή low
pluginId Το name του manifest σας. Κάθε αποστολή δηλώνει το πρόσθετο από το οποίο προέρχεται

Τα προαιρετικά πεδία περιλαμβάνουν το correlationId (ένα UUID (καθολικά μοναδικό αναγνωριστικό), διαφορετικά δημιουργείται νέο) και το callbackUrl, το οποίο χρειάζεται μια δεξιότητα plugin_queue ώστε ο worker να γνωρίζει πού να αναρτήσει το αποτέλεσμά της.

const accepted = await uno.dispatch(scope, {
  jobType: DISPATCHABLE[0],
  inputParams: { text: text.body },
  priority: "normal",
  pluginId: manifest.name,
  correlationId: crypto.randomUUID(),
});
if (!accepted.ok) return res.status(statusFor(accepted.refusal.code)).json(accepted.refusal);
res.status(202).json(accepted.value);

202, έπειτα polling

Κάθε αποστολή μπαίνει σε ουρά. Η απάντηση είναι πάντα 202 με αναγνωριστικά (jobId, runId, traceId, status), ποτέ αποτέλεσμα. Το αποτέλεσμα προέρχεται από polling της εργασίας ή από το callback σας. Το uno.peek(jobId, { scope }) το διαβάζει μία φορά και το awaitJob κάνει polling έως μια τελική κατάσταση· και τα δύο αποστέλλουν τον tenant από την επαληθευμένη εμβέλεια, και τα δύο ελέγχουν το organization_id της επιστρεφόμενης γραμμής έναντι του tenant του καλούντος από τη δική σας πλευρά της κλήσης δικτύου, απορρίπτοντας την αναντιστοιχία με SCOPE_REFUSED.

Διαβάστε τη γραμμή εκτέλεσης με τη δική της ορολογία. Η απόκριση αποστολής λέει jobId· η γραμμή λέει job_id, organization_id και plugin_id. Οι στήλες αποτελέσματος και αποτυχίας είναι result, error, error_code και error_troubleshooting. Τα completed και failed είναι τελικά. Τα timed_out, cancelled και system_failure προέρχονται από τον reaper και ένα καθυστερημένο αποτέλεσμα μπορεί ακόμη να τα διορθώσει. Ένας πελάτης που θεωρεί οποιοδήποτε από αυτά μη αναλύσιμο απορρίπτει γραμμές που η πλατφόρμα γράφει καθημερινά.

Η αναμονή έγκρισης

Μια δεξιότητα του manifest που δηλώνει approval τίθεται σε αναμονή κατά την αποστολή. Το 202 τότε λέει status: "awaiting_approval" και φέρει ένα waitpointId, με την αιτιολογία που έδωσε το manifest. Η εκτέλεση παραμένει σε αναμονή έως ότου αποφανθεί ένα κατονομαζόμενο πρόσωπο. Τα uno.approve και uno.resolveWaitpoint αποστέλλουν τον tenant και τον καλούντα ως δρώντα, και απόφαση από οποιονδήποτε άλλον εκτός του επαληθευμένου καλούντος απορρίπτεται. Μια έγκριση απελευθερώνει την εργασία μία φορά και επαναλαμβάνει τους ελέγχους αποστολής· μια απόρριψη την τερματίζει failed. Μια δεύτερη απόφαση απορρίπτεται, όπως και μια απόφαση μετά τη λήξη της αναμονής. Αν το προϊόν σας απαιτεί ο εγκρίνων να είναι διαφορετικό πρόσωπο από τον προτείνοντα, επιβάλετέ το στη διαδρομή που εκδίδει την απόφαση: η πλατφόρμα καταγράφει και τους δύο.

Εμφανίζετε μια εργασία σε αναμονή ως εργασία σε αναμονή. Μην πείτε σε ένα πρόσωπο ότι το κλικ του την απελευθέρωσε μέχρι να το δηλώνει η γραμμή εκτέλεσης.

AI: προτιμήσεις στην εγγραφή της δεξιότητας και μία ανάγνωση

Το πρόσθετό σας δεν καλεί ποτέ μοντέλο. Όταν μια δεξιότητα του manifest χρειάζεται ένα (llm_only ή tool_using, σε επίπεδο εμπιστοσύνης core ή verified), εκφράζετε προτιμήσεις στη γραμμή μητρώου της, και ο router αποφασίζει από το ίδιο το pool του οργανισμού:

{
  "execution_config_skill": {
    "preferredProvider": "gemini",
    "capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
  }
}

Τα preferredProvider και preferredModel είναι επιθυμίες που ο router τηρεί μόνο όταν ο οργανισμός έχει ενεργοποιημένο τον συγκεκριμένο πάροχο με διαπιστευτήρια. Το capabilityProfile φιλτράρει και δεν επιλέγει ποτέ· το dataResidency του (eu_only, us_only ή any) είναι αυστηρός περιορισμός που ο router είτε ικανοποιεί είτε απορρίπτει. Η παράλειψη όλων τους είναι συνήθως η σωστή επιλογή. Το modelOverride υπάρχει για τη σπάνια δεξιότητα που χρειάζεται ένα συγκεκριμένο μοντέλο, και καθιστά ανενεργές τις επιθυμίες δίπλα του· θα το απέφευγα, εκτός αν η δεξιότητα δεν έχει νόημα σε κανένα άλλο μοντέλο.

Όταν η διεπαφή σας χρειάζεται να δείξει ποιο μοντέλο θα χρησιμοποιούσε ο router, διαβάστε το, μην το προβλέπετε:

import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";

Το createAIRouteClient(...).effectiveRoute() είναι η μοναδική εγκεκριμένη ανάγνωση του AI Provider Router. Λαμβάνει τη διεύθυνση της πύλης, το bearer του ίδιου του καλούντος και το slug της πλατφόρμας σας, και δεν αποστέλλει κανένα αίτημα AI. Απαντά τον πάροχο και το μοντέλο, τους παρόχους που επιτρέπει η πολιτική και αν το επιλεγμένο endpoint εκτελεί local ή external. Όταν η διαδρομή δεν είναι χρησιμοποιήσιμη, απαντά με την άρνηση του router διατυπωμένη (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE ή NO_MODEL_FOR_ROLE_AND_PROVIDER, με την αποκατάσταση), ποτέ με προεπιλεγμένο μοντέλο. Δείξτε αυτή την άρνηση στο πρόσωπο· είναι η διαμόρφωση του δικού του οργανισμού που μιλά.

Έλεγχοι αδειών χρήσης

Τρεις μηχανισμοί ελέγχουν την αδειοδότηση, σε τρία επίπεδα λεπτομέρειας.

Ένα δικαίωμα που κατονομάζει άδεια χρήσης. Ο απλούστερος. Στο manifest, ένα δικαίωμα φέρει licence: "<feature>", και ο φύλακας ρωτά την υπηρεσία ταυτότητας αν η άδεια χρήσης του οργανισμού το περιλαμβάνει, με το token του ίδιου του καλούντος, πριν διαβαστεί οποιοσδήποτε ρόλος. Κατασκευάστε τον φύλακα με αναγνώστη:

import { createLicenceReader } from "@adverant-nexus/plugin-sdk/runtime/licence";

const requireScope = scopeMiddleware({
  verify,
  rights: { manifest, store: { pool, schema: SCHEMA }, licence: createLicenceReader({ baseUrl: config.NEXUS_AUTH_URL }) },
});

Μια άδεια χρήσης που δεν περιλαμβάνει τη λειτουργία απορρίπτει όλους με LICENCE_LOCKED, κατονομάζοντας τι την περιλαμβάνει και αναφέροντας ότι οι κάτοχοι και οι διαχειριστές του οργανισμού μπορούν να την ενεργοποιήσουν. Μια άδεια χρήσης που δεν μπορεί να διαβαστεί απορρίπτει με UNHANDLED_ERROR: μια κλειδωμένη λειτουργία δεν εξυπηρετείται ποτέ επειδή η άδεια χρήσης ήταν εκτός εμβέλειας. Οι απαντήσεις διατηρούνται για 30 δευτερόλεπτα ανά οργανισμό και λειτουργία.

Η πύλη προϊόντος. Το createProductGate({ baseUrl, product }) από το runtime/product-gate ρωτά τον έλεγχο δικαιωμάτων χρήσης αν ο οργανισμός του καλούντος κατέχει καθόλου το προϊόν σας, και το middleware() του εκτελείται μετά τον φύλακα εμβέλειας. Μια αρνητική ετυμηγορία είναι ENTITLEMENT_DENIED· ένας έλεγχος που δεν είναι προσβάσιμος είναι ENTITLEMENT_UNREACHABLE, και η πύλη δεν αντιμετωπίζει ποτέ το ένα ως το άλλο.

Το ίδιο το έγγραφο άδειας χρήσης. Ο κώδικας που πρέπει να αποφασίσει μόνος του από την υπογεγραμμένη άδεια χρήσης, όπως η κλειστή λειτουργική μονάδα ενός πακέτου τομέα, χρησιμοποιεί το verifyLicenceDocument(docText, opts) από το runtime/licence-document. Είναι καθαρή συνάρτηση: καμία κλήση δικτύου, καμία μεταβλητή περιβάλλοντος, κανένα αρχείο. Ελέγχει και τις δύο υπογραφές έναντι των ριζών εμπιστοσύνης που φέρει η έκδοση και απαντά μια κατάσταση (VALID, WARN, GRACE, RESTRICT, TERMINATE ή ABSENT) με τις παραχωρήσεις, τα πρόσθετα και τα πακέτα τομέα. Στη συνέχεια, το licenceAllows(verdict, featureGroup, action, tenantId?) δηλώνει αν μπορείτε να κάνετε use ή provision υπό μια ομάδα. Το RESTRICT επιτρέπει το use και απαντά provision με LICENCE_LOCKED, ώστε η εργασία σε εξέλιξη να συνεχίζεται και να μην ξεκινά τίποτα νέο.

Δοκιμές

Οι δοκιμές του προτύπου δείχνουν το μοτίβο· αυτά είναι τα εργαλεία πίσω από αυτό.

Ψεύτικες εμβέλειες. Κατασκευάστε το υποκατάστατο της επιλυμένης εμβέλειας μία φορά, στο test/scope-fakes.ts, και εισαγάγετέ το παντού, συμπεριλαμβανομένων των περιπτώσεων απουσίας: χωρίς μονάδα, χωρίς token, token με μηδενικό οργανισμό. Οι διαδρομές άρνησης είναι το προϊόν.

Μια ψεύτικη μεταφορά αποστολής. Το UnoClient λαμβάνει fetch, now και sleep, ώστε μια δοκιμή μονάδας να μην αγγίζει ποτέ το δίκτυο. Επιβεβαιώστε τα πεδία του φακέλου, τη μορφή του 202, το polling έως μια τελική γραμμή με το organization_id της, και ότι μια γραμμή άλλου tenant απορρίπτεται.

Μια πραγματική Postgres. Μια ψεύτικη συνάρτηση ερωτήματος αποδεικνύει μια συμβολοσειρά SQL. Δεν μπορεί να αποδείξει ότι η επιβεβλημένη ασφάλεια σε επίπεδο γραμμής ισχύει ή ότι τα αρχεία εφαρμόζονται με τη σειρά, όπως από τον migrator. Το testing/ephemeral-postgres εκκινεί έναν προσωρινό διακομιστή και εκτελεί το ίδιο nexus-migrate που εκτελεί η παραγωγή:

import { EPHEMERAL_REMEDY, migrated, startEphemeralPostgres } from "@adverant-nexus/plugin-sdk/testing/ephemeral-postgres";

const pg = await startEphemeralPostgres();          // null off CI: skip each case by name with EPHEMERAL_REMEDY
const db = migrated(pg!, "plugin_test", { root });  // provision as the superuser, then every file as the migrator
// connect as db.appUrl and run the boot checks the server runs

Εκτός CI (συνεχής ενοποίηση), ένα μηχάνημα χωρίς διακομιστή Postgres παραλείπει κάθε περίπτωση βάσης δεδομένων ονομαστικά, μαζί με τη λύση, και ποτέ δεν εμφανίζεται ως επιτυχές. Στο CI η ίδια απουσία αποτυγχάνει τη σουίτα (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), επειδή ένα παραλειφθέν τεστ ασφάλειας σε επίπεδο γραμμής είναι μια επιτυχής πύλη που δεν μέτρησε τίποτα. Ο διακομιστής περιμένει έως 180 δευτερόλεπτα για να εκκινήσει, και ένας μηχανισμός επιτήρησης τον σταματά όταν η διεργασία των τεστ τερματιστεί.

Η διάταξη ελέγχου απομόνωσης. Το runIsolationHarness(target) από το testing/isolation-harness διαβάζει κάθε διαδρομή που προσαρτά η εφαρμογή σας και επιτίθεται σε καθεμία ως διαχειριστής άλλου οργανισμού και ως συνάδελφος. Έπειτα επιτίθεται ξανά με τον φραγμό κώδικα αφαιρεμένο, τον φραγμό βάσης δεδομένων αφαιρεμένο, και με τους δύο. Μια διαδρομή είναι PROVEN μόνο όταν η επίθεση αποτυγχάνει με οποιονδήποτε από τους δύο φραγμούς στη θέση του και φτάνει στα δεδομένα του θύματος όταν αφαιρεθούν και οι δύο, ώστε να γνωρίζετε ότι το τεστ μπορεί όντως να εντοπίσει μια διαρροή. Στέλνει το δηλωμένο ερώτημα και το παράδειγμα σώματος κάθε διαδρομής, ώστε μια διαδρομή που απορρίπτει ένα κενό αίτημα να προσεγγίζεται και πάλι. Καθηλώστε το ledgerOf(report) σε ένα τεστ και αποτύχετε σε περίπτωση defectsOf(report).

Καταχώριση: από το manifest στο μητρώο δεξιοτήτων

Οι δεξιότητες του manifest σας φτάνουν στο μητρώο δεξιοτήτων μέσω μίας διαδρομής:

manifest.skills[]  →  compileRegistry(manifest)  →  POST /api/v1/plugins/sync

Το compileRegistry μετατρέπει ένα επικυρωμένο manifest στο σώμα nexus.plugin-sync/v1. Το πρότυπο το κάνει κατά την εισαγωγή, οπότε ένα μη έγκυρο manifest αποτυγχάνει τη δόμηση:

import { compileRegistry, definePlugin } from "@adverant-nexus/plugin-sdk";

export const manifest = definePlugin(raw);
export const registryPayload = compileRegistry(manifest);
{
  "contract": "nexus.plugin-sync/v1",
  "pluginId": "anomaly-review",
  "version": "0.3.0",
  "skills": [ { "job_type": "anomaly-review.excursion_summary", "tier": "host_callback", "classification": "tenant" } ]
}

Ο συγχρονισμός είναι δηλωτικός: στέλνετε ολόκληρο το σύνολο δεξιοτήτων κάθε φορά, και μια δεξιότητα που παραλείπεται απενεργοποιείται, με το ιστορικό της να διατηρείται. Είναι αυστηρός: ένα άγνωστο πεδίο, ένα πεδίο άλλου επιπέδου ή ένα null απορρίπτεται, όλες οι παραβιάσεις επιστρέφονται μαζί σε ένα 400 SYNC_CONTRACT_VIOLATION, και τίποτα δεν εγγράφεται όσο υπάρχει έστω μία. Και εγγράφει μία γραμμή μητρώου ανά δεξιότητα, με κλειδί τον τύπο εργασίας με χώρο ονομάτων, που περιέχει κάθε στήλη που διαβάζει ο dispatcher, ώστε η δεξιότητα να είναι εκτελέσιμη τη στιγμή που ο συγχρονισμός απαντά 200.

Το πρόσθετο είναι ο πιστοποιημένος καλών, ποτέ ένα πεδίο του σώματος. Καλέστε τον συγχρονισμό από το ίδιο το φορτίο εργασίας του προσθέτου σας μέσω mTLS (αμοιβαίο TLS: Transport Layer Security με πιστοποιητικό και στα δύο άκρα). Το Skills Engine διαβάζει το πιστοποιητικό πελάτη του φορτίου εργασίας σας, του οποίου η ταυτότητα SPIFFE (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) ονομάζει τον χώρο ονομάτων και τον λογαριασμό υπηρεσίας, και αναζητά το πρόσθετο και τον οργανισμό-κάτοχο που έχουν καταγραφεί για αυτόν τον χώρο ονομάτων. Το pluginId του σώματος πρέπει να ταιριάζει· είναι έλεγχος, όχι επιλογέας. Κάθε γραμμή εγγράφεται με αυτό το πρόσθετο και αυτόν τον οργανισμό.

Κατάσταση Κωδικός Σημασία
200 {contract, pluginId, version, created, updated, unchanged, disabled, skills}
400 SYNC_CONTRACT_VIOLATION Κάθε παραβίαση παρατίθεται στο violations[]· τίποτα δεν εγγράφεται
401 UNAUTHORIZED Μη έγκυρο ή ελλείπον κλειδί υπηρεσίας
401 CALLER_IDENTITY_UNVERIFIED Δεν υπάρχει αναγνώσιμη ταυτότητα πελάτη
403 DELIVERY_IDENTITY_MISSING Ο χώρος ονομάτων του καλούντος δεν ανήκει σε κανένα πρόσθετο
403 PLUGIN_ID_MISMATCH Το σώμα ονομάζει άλλο πρόσθετο
409 REGISTRY_CONFLICT Ένας τύπος εργασίας ανήκει αλλού ή καταχωρίστηκε εκτός του συγχρονισμού· τίποτα δεν εγγράφεται

Αποτύχετε το βήμα ανάπτυξης σε οποιαδήποτε κατάσταση εκτός από 200. Καμία άλλη κατάσταση δεν σημαίνει ότι οι δεξιότητές σας έχουν καταχωριστεί.

Ενσωμάτωση (Onboarding)

Η ενσωμάτωση εκτελείται σε δέκα διατεταγμένα βήματα, καθένα από τα οποία μπορεί να επανεκτελεστεί, να ακυρωθεί ή να αναιρεθεί μεμονωμένα:

  1. Κλωνοποιήστε το αποθετήριο και επικυρώστε το.
  2. Αναλύστε το manifest.
  3. Σαρώστε το για προβλήματα ασφάλειας.
  4. Δομήστε την εικόνα.
  5. Προωθήστε την στο μητρώο της εγκατάστασης.
  6. Ρυθμίστε τα ονόματα τομέα της.
  7. Αναπτύξτε την, μέσω των καναλιών έκδοσης της εγκατάστασης.
  8. Περιμένετε τον έλεγχο υγείας.
  9. Καταχωρίστε το πρόσθετο.
  10. Ενημερώστε τον προγραμματιστή.

Πριν από την ανάπτυξη, εκτελούνται πέντε έλεγχοι συμμόρφωσης στο manifest και στην εικόνα που δομήθηκε: το manifest αναλύεται και περιέχει τα απαιτούμενα πεδία του· κάθε δηλωμένη διαδρομή είναι μια πραγματική καταχωρισμένη διαδρομή· το πρόσθετο κατέχει το σχήμα του και δεν εγγράφει τίποτα εκτός αυτού· τα αιτήματα πόρων είναι δηλωμένα και εντός ορίων· και η εικόνα διαθέτει λειτουργικό χειριστή υγείας. Ένα πρόσθετο που καταχωρίζεται μόνο του κατά την εκκίνηση εκτελεί το ίδιο συμβόλαιο με δική του εξουσιοδότηση, οπότε οι έλεγχοι γίνονται το δικό του CI αντί για εκείνο της ροής. Η παράλειψη ενός ελέγχου δεν συντομεύει την ενσωμάτωση· μεταφέρει την αποτυχία στον χρόνο εκτέλεσης.

Η επωνυμία στο manifest σας εξυπηρετείται χωρίς πιστοποίηση ανά τομέα, επειδή η σελίδα σύνδεσης τη χρειάζεται πριν κάποιος διαθέτει διαπιστευτήρια. Θεωρήστε οτιδήποτε βρίσκεται στο branding δημόσιο.

Περιβάλλοντα και προώθηση
Περιβάλλοντα και προώθηση
Η ενότητα Περιβάλλοντα και προώθηση μεταφέρει κάθε έκδοση από τον χώρο ανάπτυξης μέσω του staging σε μια πιλοτική μονάδα και, στη συνέχεια, σε όλες τις μονάδες, με κάθε πύλη και την κατάστασή της σε μία σελίδα. Μια προώθηση που παρακάμπτει μια πύλη απορρίπτεται με GATE_CANNOT_BE_SKIPPED.
Κανάλια και εγκαταστάσεις
Κανάλια και εγκαταστάσεις
Η ενότητα Κανάλια και εγκαταστάσεις δείχνει ποια μονάδα εκτελεί ποια έκδοση, με τα ποσοστά σφαλμάτων ως πλήθη και ποτέ ως περιεχόμενο. Η επαναφορά μιας μονάδας είναι μια αλλαγή υπό αναθεώρηση που επηρεάζει μόνο αυτή τη μονάδα.

Τι δεν θα κάνει το περιβάλλον εκτέλεσης για εσάς

Το περιβάλλον εκτέλεσης διασφαλίζει την απομόνωση, τη διανομή εργασιών και την πρόσβαση στα μοντέλα. Δεν θα κάνει σωστή τη λογική του προϊόντος σας, ούτε θα κάνει γρήγορο ένα αργό ερώτημα: κάθε εντολή εκτελείται μέσα σε μια δεσμευμένη συναλλαγή με τα χρονικά όρια που δηλώνει το μπλοκ db του manifest σας, και μια εντολή που υπερβαίνει το statementTimeoutMs ακυρώνεται, δεν αναμένεται. Διαστασιολογήστε τα ερωτήματά σας ανάλογα. Επιπλέον, η αναμονή έγκρισης, η θέση ανάγνωσης και ο αναγνώστης αδειών προσθέτουν ο καθένας έναν κύκλο επικοινωνίας ή μια συναλλαγή. Στο πρόσθετο ελέγχου ανωμαλιών μου, ο έλεγχος άδειας πρόσθετε λίγα χιλιοστά του δευτερολέπτου ανά αίτημα μέχρι να ζεσταθεί η μνήμη 30 δευτερολέπτων του, κάτι που ήταν λογικό τίμημα για να μην εξυπηρετείται ποτέ μια κλειδωμένη λειτουργία.