Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.22
Środowisko uruchomieniowe wtyczek
Moduły pakietu SDK (software development kit), na których działa wtyczka – od strażnika zakresu i bariery bazy danych po dyspozytora UNO, odczyt trasy sztucznej inteligencji (AI) i weryfikację licencji. Następnie testowanie z użyciem rzeczywistej bazy danych, rejestrowanie umiejętności oraz wdrożenie początkowe (onboarding).
Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Część uruchomieniowa SDK (zestawu narzędzi programistycznych) to zbiór modułów w @adverant-nexus/plugin-sdk/runtime/* oraz narzędzi pomocniczych do testów w testing/*. Importują je Państwo, a nie implementują od nowa. Na tym polega cała idea i dopiero jedna odrzucona recenzja sprawiła, że potraktowałem ją poważnie: uwaga recenzenta do ręcznie napisanego sprawdzania zakresu w mojej pierwszej wtyczce składała się z jednej linijki: „SDK już to ma, a Twoja wersja akceptuje token wyzwania MFA (uwierzytelniania wieloskładnikowego) jako sesję”.
Ten rozdział śledzi żądanie przechodzące przez działającą wtyczkę w taki sposób, w jaki łączy je pełny szablon usługi: strażnik zakresu, ogrodzenie bazy danych, jedno dozwolone przejście, wysyłanie przez UNO, odczyt trasy AI (sztucznej inteligencji) oraz kontrole licencji. Następnie omawia testowanie, rejestrowanie umiejętności z manifestu oraz kroki wdrożenia.
Zakres: jeden strażnik na framework
Każda trasa /api ma strażnika zakresu. Weryfikuje on token okaziciela, wyznacza z niego trzy osie (dzierżawca, właściciel, jednostka), odrzuca treść żądania wskazującą dzierżawcę, stosuje uprawnienie trasy z rejestru manifestu i dopiero wtedy pozwala na uruchomienie procedury obsługi. SDK dostarcza jeden adapter dla każdego frameworka, wszystkie z @adverant-nexus/plugin-sdk/runtime/scope i wszystkie przyjmujące te same opcje.
| Framework | Adapter |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope, jako preHandler |
| Next | withScope, opakowujący procedurę obsługi; procedura obsługi Next nie otrzymuje informacji o swojej trasie, dlatego withScope przyjmuje ją jako trzeci argument |
Oto skrócone połączenie Express z szablonu. Weryfikator pochodzi z SDK i wymusza zgodność tokenu z formatem sesji usługi tożsamości: wyłącznie HS256; wymagane iss, exp, iat i jti; czas życia najwyżej jednej godziny; żaden token wyzwania MFA, podszywania się ani zasobu OAuth (otwartego standardu delegowanej autoryzacji) nie jest dopuszczany jako sesja.
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)) });
});Strażnik uprawnień stosuje uprawnienie trasy w czterech krokach. Rola z listy never danego uprawnienia powoduje odmowę z AUTHORITY_EXCEEDED i komunikatem barred, a żadne stanowisko tego nie znosi. Rola z roles dopuszcza, wraz z aktywnym stanowiskiem, gdy uprawnienie określa seat: true. W przeciwnym razie dopuszcza aktywne stanowisko posiadające to uprawnienie. W przeciwnym razie żądanie jest odrzucane z AUTHORITY_EXCEEDED, ze wskazaniem osób, które mogłyby przyznać stanowisko. Jeśli przekażą Państwo strażnikowi magazyn (rights: { manifest, store: { pool, schema } }), odczytuje on stanowiska w zakresie samego wywołującego; uprawnienie wskazujące licence wymaga także czytnika licencji, opisanego poniżej.
Wewnątrz procedury obsługi scopeOf(req) jest jedynym sposobem odczytania wyznaczonego zakresu i zgłasza wyjątek, jeśli strażnik nie został uruchomiony. Strażnik zarejestrowany na prefiksie, uruchamiany przed dopasowaniem jakiejkolwiek trasy, odpowiada 500 MIDDLEWARE_ORDERING_ERROR; trasa zarejestrowana przez Państwa kod, której manifest nie deklaruje, odpowiada 500 UNHANDLED_ERROR. Oba przypadki kończą się bezpieczną odmową.
Trasy /internal szablonu, wywoływane przez platformę, podlegają innemu reżimowi. Strażnik usługi sprawdza X-Service-Key w stałym czasie i pobiera dzierżawcę z X-Organization-ID platformy, odrzucając MISSING_SERVICE_KEY, INVALID_SERVICE_KEY lub MISSING_ORG_ID_HEADER. Dla podpisanego tokenu platformy, wydawanego na każde wywołanie, SDK udostępnia requireService (Fastify) i serviceMiddleware (Express), które sprawdzają również, dla jakiej umiejętności i trasy token został wystawiony, oraz odrzucają token użyty dwukrotnie.
Ogrodzenie bazy danych: tenantFence i withScopedTx
Każda instrukcja wykonywana na tabeli objętej zakresem składa ogrodzenie i działa wewnątrz transakcji objętej zakresem:
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) buduje predykat i jego parametry z wyznaczonego zakresu. Dla tabel osobistych należy przekazać owner; dla artefaktów organizacji, w których właściciel oznacza pochodzenie, należy go pominąć. Gdy instrukcja ma już parametry, startIndex wskazuje ogrodzeniu, od jakiego numeru zacząć numerację. Wstawianie nigdy nie przyjmuje osi jako danych wejściowych: zapisuje scope.tenant, scope.owner i scope.unit z zakresu.
withScopedTx wiąże wszystkie trzy osie dla jednej transakcji za pomocą jedynej funkcji wiążącej schematu, a następnie uruchamia Państwa wywołanie zwrotne. Drugie powiązanie w tej samej transakcji zgłasza SCOPE_ALREADY_BOUND (500: Państwa kod powiązał dwukrotnie; wywołujący nie popełnił błędu). Brak lub zerowa wartość dzierżawcy albo właściciela zgłasza SCOPE_PREDICATE_INVALID (403). Ustawienie jest lokalne dla transakcji, więc połączenie z puli nie przeniesie jednego dzierżawcy do następnego żądania.
Dwie pokrewne funkcje obejmują przypadki, które nie są żądaniem osoby. withTenantScopedTx wiąże dzierżawcę i jednostkę bez właściciela, dla wierszy odczytywanych przez maszynę (rejestr urządzeń), i odrzuca zakres zawierający właściciela. maintenanceScope(reason) wymaga, aby operacja obejmująca całą organizację jawnie określiła, czym jest, zanim otworzy się transakcja właściciela. Ogrodzenie w kodzie i wymuszone zabezpieczenia na poziomie wierszy to dwa mechanizmy jednej zasady; kontrola przy uruchomieniu odmawia nasłuchiwania, dopóki baza danych nie udowodni, że druga z nich obowiązuje (w przeciwnym razie DB_ROLE_BYPASSES_ISOLATION).
Każda odmowa jest zapisywana jako wiersz
Szablon instaluje jeszcze jeden element oprogramowania pośredniczącego, jednokrotnie, między parserem treści a routerami: rejestr odmów.
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));Opakowuje on odpowiedź tak, aby każda odmowa, którą odczytuje osoba, czy to od strażnika uprawnień, procedury obsługi, czy magazynu, została zapisana w tabeli refusal Państwa schematu w ramach transakcji objętej zakresem tej osoby, zanim treść zostanie wysłana. Anonimowa odpowiedź 401 niczego nie zapisuje. Jeśli wiersza nie można zapisać, odpowiedzią staje się UNHANDLED_ERROR: „nie”, którego produkt nie może zarejestrować, nie jest wysyłane tak, jakby zostało zarejestrowane. Przy uruchomieniu wykonywane jest assertRefusalLedger, aby sprawdzić, czy tabela może przyjąć wiersz rejestru, a magazyn może wywołać noteSubject({ recordId, isDemo }), aby każda odmowa wskazywała rekord, którego dotyczyła. Gdy klient zapyta, dlaczego ktoś został odprawiony w zeszły wtorek, odpowiedzią jest zapytanie, a nie domysł.
Jedyne przejście między granicami: zarejestrowane uprawnienie tylko do odczytu
Gdy jeden z Państwa klientów wykonuje pracę dla innego, a ten drugi może ją kontrolować, istnieje jeden zatwierdzony sposób przekroczenia granicy. Organizacja przechowująca wiersze rejestruje przyznanie dostępu. Organizacja czytającego dopuszcza osobę poprzez stanowisko posiadające uprawnienie granted.read, które musi wskazywać owner i admin w never. Odczyt działa jako szósta rola bazy danych, stanowisko odczytu, które może wybierać dane wyłącznie z tabel wymienionych w 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 najpierw zapisuje wgląd we własnym dzierżawcy czytającego, a następnie wiąże stanowisko odczytu z przyznaniem dostępu, co zapisuje wgląd w dzierżawcy przechowującego. Własna polityka bazy danych sprawdza, czy przyznanie wskazuje organizację czytającego, obejmuje tabelę, rozpoczęło się, nie zakończyło się i nie zostało wycofane, a także czy ta transakcja zapisała swój wgląd. Odczyt pomijający wgląd nie widzi niczego. Przy uruchomieniu assertSeatAtBoot(seatPool, schema) sprawdza, czy pula otwarta z seat.url jest rzeczywiście stanowiskiem i niczym więcej, a w przeciwnym razie odmawia z DB_SEAT_ROLE_INVALID.
Dysponowanie zadań przez UNO
Wszystkie obliczenia przechodzą przez jednego klienta, zbudowanego w jednym pliku, z zamkniętą listą dozwolonych:
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,
});
}Lista dozwolonych jest celowo stałą na poziomie modułu. Gdyby operator mógł ją rozszerzyć w konfiguracji, trasa stałaby się pośrednikiem wysyłania dla całego rejestru. Własny test szablonu sprawdza, czy lista wymienia dokładnie te typy zadań, do których kompiluje się manifest.
Koperta
Wysłanie zawiera w wymaganym rdzeniu sześć pól. Klient wypełnia dzierżawcę i aktora na podstawie zweryfikowanego zakresu, nigdy na podstawie żądania:
| Pole | Co zawiera |
|---|---|
jobType |
Typ zadania z przestrzenią nazw, <plugin name>.<skill id> |
organizationId |
Dzierżawca, z zakresu |
userId |
Aktor, z zakresu, na potrzeby audytu i rozliczeń |
inputParams |
Dane wejściowe umiejętności. Nigdy nie zawierają identyfikatora dzierżawcy; dane, które go zawierają, są odrzucane przy wysyłaniu |
priority |
critical, high, normal lub low |
pluginId |
name Państwa manifestu. Każde wysłanie deklaruje wtyczkę, z której pochodzi |
Pola opcjonalne obejmują correlationId (UUID (uniwersalny unikalny identyfikator); w przeciwnym razie generowany jest nowy) oraz callbackUrl, którego potrzebuje umiejętność plugin_queue, aby proces roboczy wiedział, dokąd wysłać wynik.
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, a następnie odpytywanie
Każde wysłanie trafia do kolejki. Odpowiedzią jest zawsze 202 z identyfikatorami (jobId, runId, traceId, status), nigdy wynik. Wynik pochodzi z odpytywania zadania lub z Państwa wywołania zwrotnego. uno.peek(jobId, { scope }) odczytuje go jednokrotnie, a awaitJob odpytuje aż do statusu końcowego; obie funkcje wysyłają dzierżawcę ze zweryfikowanego zakresu i obie sprawdzają organization_id zwróconego wiersza względem dzierżawcy wywołującego po Państwa stronie wywołania sieciowego, odrzucając niezgodność z SCOPE_REFUSED.
Wiersz uruchomienia należy odczytywać w jego własnej pisowni. Odpowiedź wysłania zawiera jobId; wiersz zawiera job_id, organization_id i plugin_id. Kolumny wyniku i błędu to result, error, error_code i error_troubleshooting. completed i failed są końcowe. timed_out, cancelled i system_failure pochodzą od procesu porządkującego i późny wynik może je jeszcze skorygować. Klient, który traktuje którykolwiek z nich jako nieparsowalny, odrzuca wiersze zapisywane przez platformę każdego dnia.
Wstrzymanie do zatwierdzenia
Umiejętność z manifestu, która deklaruje approval, jest wstrzymywana przy wysyłaniu. 202 zawiera wtedy status: "awaiting_approval" oraz waitpointId z powodem podanym w manifeście. Uruchomienie pozostaje wstrzymane, dopóki wskazana osoba nie podejmie decyzji. uno.approve i uno.resolveWaitpoint wysyłają dzierżawcę oraz wywołującego jako aktora, a decyzja podjęta przez osobę inną niż zweryfikowany wywołujący jest odrzucana. Zatwierdzenie zwalnia zadanie jednokrotnie i ponownie wykonuje kontrole wysyłania; odrzucenie kończy je z failed. Druga decyzja jest odrzucana, podobnie jak decyzja po wygaśnięciu wstrzymania. Jeśli Państwa produkt wymaga, aby zatwierdzający był inną osobą niż proponujący, należy to wymusić w trasie podejmującej decyzję: platforma rejestruje obie osoby.
Wstrzymane zadanie należy wyświetlać jako wstrzymane. Nie należy informować osoby, że jej kliknięcie je zwolniło, dopóki wiersz uruchomienia tego nie potwierdzi.
AI: preferencje w wierszu umiejętności i jeden odczyt
Państwa wtyczka nigdy nie wywołuje modelu. Gdy umiejętność z manifestu go potrzebuje (llm_only lub tool_using, na poziomie zaufania core lub verified), wyrażają Państwo preferencje w jej wierszu rejestru, a router decyduje na podstawie własnej puli organizacji:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"capabilityProfile": { "needsToolUse": true, "dataResidency": "eu_only" }
}
}preferredProvider i preferredModel to życzenia, które router respektuje tylko wtedy, gdy organizacja ma danego dostawcę włączonego i skonfigurowanego z poświadczeniami. capabilityProfile filtruje i nigdy nie wybiera; jego dataResidency (eu_only, us_only lub any) jest twardym ograniczeniem, które router spełnia albo odmawia. Pominięcie ich wszystkich jest zwykle właściwe. modelOverride istnieje dla rzadkiej umiejętności, która potrzebuje jednego konkretnego modelu, i czyni towarzyszące mu życzenia nieskutecznymi; unikałbym go, chyba że umiejętność nie ma sensu na żadnym innym modelu.
Gdy Państwa interfejs musi pokazać, którego modelu użyłby router, należy to odczytać, a nie przewidywać:
import { createAIRouteClient } from "@adverant-nexus/plugin-sdk/runtime/ai-route";createAIRouteClient(...).effectiveRoute() to jedyny zatwierdzony odczyt AI Provider Router. Przyjmuje adres bramy, własny token okaziciela wywołującego oraz slug Państwa platformy i nie wysyła żadnego żądania AI. Zwraca dostawcę i model, dostawców dozwolonych przez politykę oraz informację, czy wybrany punkt końcowy działa w trybie local czy external. Gdy trasy nie można użyć, zwraca słowną odmowę routera (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE lub NO_MODEL_FOR_ROLE_AND_PROVIDER, wraz ze sposobem naprawy), nigdy model domyślny. Należy pokazać tę odmowę osobie; to przemawia konfiguracja jej organizacji.
Weryfikacja licencji
Licencje sprawdzają trzy mechanizmy, na trzech poziomach szczegółowości.
Uprawnienie wskazujące licencję. Najprostszy. W manifeście uprawnienie zawiera licence: "<feature>", a strażnik pyta usługę tożsamości, czy licencja organizacji to obejmuje, używając własnego tokenu wywołującego, zanim zostanie odczytana jakakolwiek rola. Strażnika należy zbudować z czytnikiem:
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 }) },
});Licencja, która nie obejmuje funkcji, odmawia wszystkim z LICENCE_LOCKED, wskazując, co ją obejmuje, i informując, że właściciele i administratorzy organizacji mogą ją włączyć. Licencja, której nie można odczytać, powoduje odmowę z UNHANDLED_ERROR: zablokowana funkcja nigdy nie jest udostępniana dlatego, że licencja była nieosiągalna. Odpowiedzi są zapamiętywane na 30 sekund dla każdej organizacji i funkcji.
Bramka produktu. createProductGate({ baseUrl, product }) z runtime/product-gate pyta kontrolę uprawnień licencyjnych, czy organizacja wywołującego w ogóle posiada Państwa produkt, a jego middleware() działa po strażniku zakresu. Werdykt negatywny to ENTITLEMENT_DENIED; kontrola, z którą nie można się połączyć, to ENTITLEMENT_UNREACHABLE, a bramka nigdy nie traktuje jednego jak drugiego.
Sam dokument licencji. Kod, który musi samodzielnie decydować na podstawie podpisanej licencji, na przykład zamknięty moduł pakietu domenowego, używa verifyLicenceDocument(docText, opts) z runtime/licence-document. Jest to czysta funkcja: bez wywołań sieciowych, bez zmiennych środowiskowych, bez plików. Sprawdza oba podpisy względem kotwic zaufania zawartych w kompilacji i zwraca stan (VALID, WARN, GRACE, RESTRICT, TERMINATE lub ABSENT) wraz z uprawnieniami, dodatkami i pakietami domenowymi. licenceAllows(verdict, featureGroup, action, tenantId?) określa następnie, czy wolno use lub provision w ramach grupy. RESTRICT dopuszcza use i odpowiada provision z LICENCE_LOCKED, dzięki czemu trwająca praca jest kontynuowana, a nic nowego się nie rozpoczyna.
Testowanie
Testy szablonu pokazują wzorzec; oto narzędzia, które za nim stoją.
Atrapy zakresu. Należy raz zbudować dublera wyznaczonego zakresu w test/scope-fakes.ts i wstrzykiwać go wszędzie, łącznie z przypadkami braku: brak jednostki, brak tokenu, token z zerową organizacją. Ścieżki odmowy są produktem.
Atrapa transportu wysyłania. UnoClient przyjmuje fetch, now i sleep, dzięki czemu test jednostkowy nigdy nie korzysta z sieci. Należy sprawdzić pola koperty, kształt 202, odpytywanie aż do wiersza końcowego z jego organization_id oraz to, że wiersz innego dzierżawcy jest odrzucany.
Prawdziwy Postgres. Fałszywa funkcja zapytania potwierdza jedynie ciąg SQL. Nie może potwierdzić, że wymuszone zabezpieczenia na poziomie wierszy działają ani że pliki są stosowane we właściwej kolejności, tak jak robi to migrator. testing/ephemeral-postgres uruchamia tymczasowy serwer i wykonuje te same nexus-migrate, które wykonuje środowisko produkcyjne:
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 runsPoza CI (ciągłą integracją) maszyna bez serwera Postgres pomija każdy przypadek bazodanowy, podając jego nazwę i sposób naprawy, nigdy nie zgłaszając wyniku pozytywnego. W CI ten sam brak powoduje niepowodzenie zestawu testów (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI), ponieważ pominięty test zabezpieczeń na poziomie wierszy to pozytywna bramka, która niczego nie zmierzyła. Serwer czeka na uruchomienie do 180 sekund, a mechanizm nadzorczy zatrzymuje go, gdy proces testowy się zakończy.
Mechanizm testowania izolacji. runIsolationHarness(target) z testing/isolation-harness odczytuje każdą trasę montowaną przez Państwa aplikację i atakuje każdą z nich jako administrator innej organizacji oraz jako współpracownik. Następnie atakuje ponownie po usunięciu zabezpieczenia w kodzie, zabezpieczenia w bazie danych oraz obu. Trasa otrzymuje status PROVEN tylko wtedy, gdy atak kończy się niepowodzeniem przy którymkolwiek zabezpieczeniu, a po usunięciu obu dociera do danych ofiary, dzięki czemu wiadomo, że test w ogóle jest w stanie wykryć wyciek. Wysyła on zadeklarowane zapytanie i przykładową treść każdej trasy, więc trasa odrzucająca puste żądanie również zostanie osiągnięta. Proszę przypiąć ledgerOf(report) w teście i zgłaszać niepowodzenie przy defectsOf(report).
Rejestracja: od manifestu do rejestru umiejętności
Umiejętności z Państwa manifestu trafiają do rejestru umiejętności jedną ścieżką:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
compileRegistry przekształca zweryfikowany manifest w treść nexus.plugin-sync/v1. Szablon robi to podczas importu, więc nieprawidłowy manifest powoduje niepowodzenie kompilacji:
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" } ]
}Synchronizacja jest deklaratywna: za każdym razem należy wysłać cały zestaw umiejętności, a pominięta umiejętność zostaje wyłączona z zachowaniem jej historii. Jest rygorystyczna: nieznane pole, pole innej warstwy lub null zostają odrzucone, wszystkie naruszenia są zwracane razem w jednym 400 SYNC_CONTRACT_VIOLATION i nic nie jest zapisywane, dopóki istnieje choć jedno. Zapisuje też jeden wiersz rejestru na umiejętność, z kluczem w postaci typu zadania z przestrzenią nazw, zawierający każdą kolumnę odczytywaną przez dyspozytor, więc umiejętność można uruchomić, gdy tylko synchronizacja odpowie 200.
Wywołującym uwierzytelnionym jest wtyczka, nigdy pole w treści. Synchronizację należy wywoływać z własnego obciążenia wtyczki przez mTLS (wzajemne TLS: Transport Layer Security z certyfikatem po obu stronach). Skills Engine odczytuje certyfikat klienta Państwa obciążenia, którego tożsamość SPIFFE (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>) wskazuje przestrzeń nazw i konto usługi, i wyszukuje wtyczkę oraz organizację będącą właścicielem zarejestrowane dla tej przestrzeni nazw. Wartość pluginId w treści musi się zgadzać; jest to weryfikacja, a nie selektor. Każdy wiersz jest zapisywany z tą wtyczką i organizacją.
| Status | Kod | Znaczenie |
|---|---|---|
| 200 | {contract, pluginId, version, created, updated, unchanged, disabled, skills} |
|
| 400 | SYNC_CONTRACT_VIOLATION |
Każde naruszenie wymienione w violations[]; nic nie zapisano |
| 401 | UNAUTHORIZED |
Nieprawidłowy lub brakujący klucz usługi |
| 401 | CALLER_IDENTITY_UNVERIFIED |
Brak czytelnej tożsamości klienta |
| 403 | DELIVERY_IDENTITY_MISSING |
Wywołująca przestrzeń nazw nie należy do żadnej wtyczki |
| 403 | PLUGIN_ID_MISMATCH |
Treść wskazuje inną wtyczkę |
| 409 | REGISTRY_CONFLICT |
Typ zadania należy do innego właściciela lub został zarejestrowany poza synchronizacją; nic nie zapisano |
Proszę przerywać krok wdrożenia przy każdym statusie innym niż 200. Żaden inny status nie oznacza, że Państwa umiejętności zostały zarejestrowane.
Wdrożenie początkowe (onboarding)
Wdrażanie przebiega w dziesięciu uporządkowanych krokach, z których każdy można niezależnie ponowić, anulować lub wycofać:
- Sklonowanie repozytorium i jego weryfikacja.
- Przetworzenie manifestu.
- Skanowanie go pod kątem problemów z bezpieczeństwem.
- Zbudowanie obrazu.
- Wypchnięcie go do rejestru instalacji.
- Skonfigurowanie jego nazw domen.
- Wdrożenie go za pośrednictwem kanałów wydań instalacji.
- Oczekiwanie na kontrolę kondycji.
- Zarejestrowanie wtyczki.
- Powiadomienie dewelopera.
Przed wdrożeniem wobec manifestu i zbudowanego obrazu wykonywanych jest pięć kontroli zgodności: manifest daje się przetworzyć i zawiera wymagane pola; każda zadeklarowana trasa jest rzeczywiście zarejestrowaną trasą; wtyczka jest właścicielem swojego schematu i niczego nie zapisuje poza nim; żądania zasobów są zadeklarowane i mieszczą się w limitach; a obraz ma działającą procedurę obsługi kontroli kondycji. Wtyczka, która rejestruje się sama podczas uruchamiania, wykonuje ten sam kontrakt we własnym zakresie uprawnień, więc kontrole stają się jej CI zamiast CI potoku. Pominięcie którejś z nich nie skraca wdrażania; przenosi jedynie błąd do czasu działania.
Elementy marki z Państwa manifestu są udostępniane bez uwierzytelniania według domeny, ponieważ strona logowania potrzebuje ich, zanim ktokolwiek uzyska poświadczenia. Wszystko w branding należy traktować jako publiczne.
GATE_CANNOT_BE_SKIPPED.Czego środowisko uruchomieniowe nie zrobi za Ciebie
Środowisko uruchomieniowe pilnuje izolacji, dyspozycji i dostępu do modeli. Nie sprawi, że Państwa logika produktu będzie poprawna, ani nie przyspieszy wolnego zapytania: każda instrukcja jest wykonywana w powiązanej transakcji z limitami czasu zadeklarowanymi w bloku db Państwa manifestu, a instrukcja przekraczająca statementTimeoutMs zostaje anulowana, a nie oczekuje się na nią. Proszę dopasować do tego swoje zapytania. Ponadto wstrzymanie do zatwierdzenia, miejsce do odczytu i czytnik licencji dodają po jednym dodatkowym przebiegu w obie strony lub jednej transakcji. W mojej wtyczce do przeglądu anomalii sprawdzanie licencji dodawało kilka milisekund na żądanie, dopóki jej 30-sekundowa pamięć podręczna się nie rozgrzała, co było uczciwą ceną za to, że nigdy nie udostępniono zablokowanej funkcji.

