Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.21
Pakiet Plugin SDK
Instalacja pakietu Plugin SDK (software development kit), jego narzędzia wiersza poleceń, przegląd szablonu pełnej usługi, omówienie manifestu v2 pole po polu oraz dwadzieścia dwie bramki pilnujące zgodności wtyczki z regułami.
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

Moja druga wtyczka zajęła jedną trzecią czasu pierwszej, a niemal cała oszczędność wynikała z SDK (software development kit). Za pierwszym razem napisałem sprawdzanie zakresu, moduł ładowania konfiguracji i moduł uruchamiania migracji, a recenzent odesłał każdy z nich do poprawy. Za drugim razem uruchomiłem jedno polecenie tworzące szkielet, usunąłem przykładową umiejętność analizy sentymentu i poświęciłem swoje dni na rekordy przeglądu anomalii, których faktycznie potrzebował nasz zespół dynamiki lotu.
@adverant-nexus/plugin-sdk to jeden pakiet npm. Zawiera schemat manifestu v2 i walidatory, które go odczytują (definePlugin, defineSkill), moduły środowiska uruchomieniowego importowane przez wtyczkę do obsługi zakresu, bazy danych, dyspozycji i pozostałych funkcji, narzędzia pomocnicze do testów, bramki zgodności oraz narzędzia wiersza poleceń. Ten rozdział omawia jego instalację, narzędzia, szablon, manifest i bramki. Rozdział 2.22, Środowisko uruchomieniowe wtyczek, omawia moduły środowiska uruchomieniowego w działającym kodzie.
Instalacja
Pakiet pochodzi z rejestru Adverant pod adresem https://registry.adverant.ai/npm/, nigdy z publicznego rejestru npm, i potrzebny jest token pobierania ze strony „Tokeny pobierania i polecenia instalacji” Państwa konta. Należy skierować zakres @adverant-nexus na ten rejestr w pliku .npmrc repozytorium:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> to token ze strony konta. W potoku należy przekazywać go z sekretu i nigdy go nie zatwierdzać w repozytorium; plik Dockerfile szablonu odmawia kompilacji bez niego i usuwa .npmrc z etapu budowania po wykonaniu npm ci, dzięki czemu token nigdy nie trafia do obrazu.
Następnie należy przypiąć dokładną wersję:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Przy pierwszej instalacji należy zatwierdzić package-lock.json. Budowanie obrazu w szablonie uruchamia npm ci i odmawia przejścia awaryjnego na npm install: plik blokady jest kontraktem. Minimalną wersją dla samego SDK jest Node 18; szablon jest przeznaczony dla Node 20.
Narzędzia wiersza poleceń są dostarczane w pakiecie, dlatego każde polecenie w tej dokumentacji wskazuje pakiet i jego wersję za pomocą npx -p. Samo npx create-nexus-plugin jest wyszukiwane w publicznym rejestrze, a ta nazwa nie oznacza tego pakietu.
Narzędzia wiersza poleceń
| Narzędzie | Co robi |
|---|---|
create-nexus-plugin |
Tworzy szkielet wtyczki, waliduje manifest, migruje manifest v1 do v2 i generuje przewodnik dla użytkownika dla programisty frontendu |
nexus-tenancy |
Generuje z manifestu kod SQL dotyczący dzierżawców dla schematu: role, uprawnienia, szablon zabezpieczeń na poziomie wierszy i tabele grafu |
nexus-migrate |
Stosuje migracje: jednorazowo tworzy role, a następnie uruchamia każdy numerowany plik jako rola migratora |
nexus-gates |
Uruchamia każdą bramkę zgodności oraz autotest każdej bramki |
create-nexus-plugin nie wykonuje żadnych wywołań sieciowych ani nie ładuje zdalnego kodu. Uruchamia te same walidatory w procesie, których używa proces wdrażania platformy, więc nie ma rozbieżności między „przeszło walidację na mojej maszynie” a „platforma to zaakceptowała”.
| Polecenie | Flagi | Co robi | Kody wyjścia |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Zapisuje nowy katalog wtyczki; --print wyświetla tylko manifest |
0 zapisano · 1 odmowa nadpisania · 2 nieprawidłowe użycie |
validate <file> |
Waliduje plik nexus.manifest.json albo moduł .ts lub .js, który go eksportuje |
0 prawidłowy · 1 nieprawidłowy lub nieczytelny · 2 nieprawidłowe użycie | |
migrate <file> |
--write |
Przekształca manifest v1 do v2 i wyświetla go lub zapisuje w miejscu | 0 · 1 · 2, jak wyżej |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Generuje przewodnik dla użytkownika z manifestu i Państwa opisu; --check porównuje go z zatwierdzoną kopią i niczego nie zapisuje |
0 · 1 rozbieżność lub naruszenie reguł lintera · 2 nieprawidłowe użycie |
help |
Wyświetla sposób użycia | 0 |
Generowanie szkieletu (scaffolding) i trzy warstwy
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier domyślnie przyjmuje wartość full-service. Generator szkieletu odmawia zapisu do istniejącego katalogu, a zapisywany przez niego manifest już przechodzi walidację; nigdy nie tworzy nieprawidłowego.
Poziom należy wybrać na podstawie tego, co zawiera wtyczka.
| Poziom | Zawiera | Musi zadeklarować |
|---|---|---|
skills-only |
Wyłącznie umiejętności manifestu | skills[], z co najmniej jednym wpisem |
ui-only |
Interfejs frontendu wewnątrz powłoki | frontend |
full-service |
Backend i frontend, zwykle z własnym schematem | backend i frontend; a ponieważ ma backend, również runtime.healthCheck |
W razie wątpliwości należy utworzyć szkielet full-service i usunąć to, co niepotrzebne. Postępowanie odwrotne oznacza samodzielne pisanie elementów, które zapewniłby szablon.
Przegląd szablonu pełnej usługi
Szablon to wtyczka referencyjna, zbudowana według ścisłego wzorca zakładanego we wszystkich kolejnych rozdziałach. Należy powielać jego strukturę, a nie przykładową logikę.
| Ścieżka | Czym to jest |
|---|---|
nexus.manifest.json |
Manifest v2: ponownie przytoczone trzy zasady, tabela tras i jej rejestr uprawnień |
src/config.ts |
Moduł ładowania konfiguracji. Jedna specyfikacja, odczytywana raz, a wszystkie problemy są zbierane, zanim proces odmówi uruchomienia |
src/scope.ts |
Jedyny plik, który przekształca żądanie w zakres, ze ścisłym weryfikatorem tokenów SDK i dwoma trybami: tokenem okaziciela osoby oraz wywołaniem usługi platformy |
src/db.ts |
Każda instrukcja składa tenantFence() i jest wykonywana wewnątrz withScopedTx |
src/uno.ts |
Jedyny plik dyspozycji: jeden adres URL, jeden klient, zamknięta lista dozwolonych |
src/routes/*.ts |
health (anonimowa, dokładna ścieżka), trasy /api (w zakresie) i wywołanie zwrotne /internal (chronione usługowo) |
src/skills/sentiment.ts |
Deterministyczna umiejętność host_callback; leksykon należy zastąpić własną logiką |
src/server.ts |
Korzeń kompozycji: jednorazowo instaluje rejestr odmów, czeka (w ograniczonym czasie) na bazę danych, a następnie przed rozpoczęciem nasłuchu wykonuje kontrole izolacji i rejestru |
migrations/000_tenancy.sql |
Generowane przez nexus-tenancy render podczas tworzenia szkieletu: role, schemat, szablon zabezpieczeń na poziomie wierszy |
migrations/001_init.sql |
Dwie tabele ze złożonym kluczem rozpoczynającym się od dzierżawcy oraz złożonym kluczem obcym zawierającym dzierżawcę |
migrations/002_refusal_ledger.sql |
Tabela, do której zapisuje rejestr odmów |
scripts/ci/required-env |
Wyświetla w formacie JSON nazwy zmiennych środowiskowych wymaganych przy uruchomieniu |
scripts/ci/shadow-migrate-*.sh |
Próbne uruchomienie migracji w potoku za pomocą nexus-migrate |
gates/ |
Katalog wyjątków bramek: pusty, co jest prawidłowym stanem dla nowej wtyczki |
test/ |
Testy zakresu, tras, bazy danych, dyspozycji i uruchamiania, z dublerami zakresu wstrzykiwanymi w każdym teście |
Dockerfile |
Obraz uruchamiany bez uprawnień roota (identyfikator użytkownika 10001), zawierający migracje |
Kilku z tych plików warto przyjrzeć się bliżej.
src/config.ts stosuje dwie zasady. Zbiera wszystkie problemy przed zgłoszeniem błędu, więc jedno ponowne uruchomienie wskazuje wszystkie pięć brakujących zmiennych zamiast pięciu ponownych uruchomień wskazujących po jednej. Wartość domyślną przyjmuje tylko wtedy, gdy błędna wartość nie może dać niezauważalnie błędnego wyniku: PORT może mieć domyślnie 8080, ponieważ błędny port powoduje widoczny błąd powiązania, natomiast DATABASE_URL i UNO_DISPATCH_URL są wymagane i muszą być adresami wewnątrz klastra. Adres publiczny jest odrzucany przy uruchomieniu.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Własny test szablonu uruchamia ten plik i porównuje jego wynik z nazwami oznaczonymi w specyfikacji konfiguracji jako wymagane, więc dodanie wymaganej zmiennej bez zaktualizowania listy powoduje niepowodzenie npm test.
src/server.ts nie rozpoczyna nasłuchu, dopóki baza danych nie odpowie, i ogranicza czas oczekiwania do 120 sekund, rejestrując każdą nieudaną próbę wraz z jej przyczyną. Następnie kolejno potwierdza, że rola aplikacji nie może ponownie powiązać dzierżawcy, a każda tabela ma wymuszone zabezpieczenia na poziomie wierszy, że pula każdego poda mieści się w limicie połączeń roli oraz że tabela rejestru odmów może przyjąć wiersz. Odmowa z dowolnej z tych trzech kontroli jest wyświetlana w całości, a proces kończy się kodem 2.
Manifest v2, pole po polu
Manifest jest odczytywalnym maszynowo kontraktem wtyczki z platformą. Jest walidowany podczas tworzenia, podczas wdrażania na platformie, a następnie w sposób ciągły. Schemat ma additionalProperties: false na każdym poziomie: jeśli wtyczka ma daną sekcję, istnieje dla niej właściwość, a niezadeklarowany klucz jest odrzucany. Rozwiązaniem jest zawsze użycie właściwej opcjonalnej właściwości.
Wymagany rdzeń
| Pole | Reguła |
|---|---|
manifestVersion |
Dokładnie "2". Dokument v1 jest migrowany, nigdy ponownie walidowany w miejscu |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, maksymalnie 64 znaki. Identyfikator wtyczki używany przy rejestracji, w przestrzeniach nazw dyspozycji i w wierszach w zakresie dzierżawcy. Wtyczka deklarująca umiejętności potrzebuje również nazwy bez kropki i bez cyfry na początku |
displayName |
Od 1 do 120 znaków |
version |
Wersjonowanie semantyczne; własny cykl wydań |
description, author, license |
Co najmniej jeden znak każde |
tier |
skills-only, ui-only lub full-service |
trust |
core, verified, community lub untrusted |
runtime |
Wymagane: executionMode, isolationLevel (od 1 do 4), entrypoint. Opcjonalne: nodeVersion, healthCheck, readinessCheck, livenessCheck, każde jako ścieżka zaczynająca się od /. Tryb wynika z poziomu: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai i deploy, ponownie przytoczone trzy zasady platformy. Walidator ustala ich brzmienie |
W przypadku wtyczki tworzonej dla własnej instalacji trzy zdania brzmią następująco. Zdanie ai dotyczy sztucznej inteligencji (AI) i jest miejscem, w którym należy stwierdzić, że wtyczka nie przechowuje poświadczeń modeli.
"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."
}Tabela tras: api i rights
api wymaga version i basePath, a opcjonalnie websocket (path, auth) i endpoints[]. Tabela tras jest najmocniejszą koncepcją schematu: bramka porównuje ją z trasami faktycznie rejestrowanymi przez kod, w obu kierunkach, dzięki czemu manifest jest weryfikowalnym kontraktem, a nie dokumentacją.
Każdy punkt końcowy wymaga method (GET, POST, PUT, PATCH lub DELETE) oraz path. Pozostałe:
| Pole | Co określa |
|---|---|
auth |
Jedna z pięciu klas: scope (trasa osoby, za strażnikiem zakresu), service-key i internal (serwer–serwer, nigdy niedostępne z przeglądarki), public (zawsze wyłącznie dokładna ścieżka z allowAnonymous) oraz device (maszyna z własnym poświadczeniem, za strażnikiem urządzeń) |
right |
Wymagane na każdej trasie obsługiwanej przez strażnika zakresu i odrzucane na każdej innej: nazwa uprawnienia z rejestru rights |
needsUnit |
Trasa odmawia, gdy nie można ustalić jednostki wywołującego |
allowAnonymous |
Wyłącznie lista dozwolonych z dokładnym dopasowaniem. Reguła prefiksowa to sposób, w jaki /health-of-tenant-42 staje się publiczne |
group, serves, screens |
W bloku release: grupa funkcji obsługiwana przez trasę, odpowiedź trasy, gdy licencjonowana funkcja tej grupy jest zablokowana (data, teaser, sighting lub ask), oraz obsługiwane przez nią ekrany |
query |
required (każda nazwa z przykładową wartością) i allowed: parametry zapytania odczytywane przez trasę |
body |
example: przykładowa treść żądania trasy zapisu, akceptowana przez jej własny walidator. Nigdy w przypadku GET |
rights to rejestr, do którego odwołują się te trasy. Każde uprawnienie ma roles (pułap) i opcjonalnie summary, never (role, które nigdy nie mogą z niego korzystać, niezależnie od innych posiadanych uprawnień), barred (własne sformułowanie produktu przy odmowie dla roli never), seat (wymagane jest również aktywne stanowisko), self (posiada je każda zweryfikowana osoba, w przypadku uprawnień do własnej sesji), grants (posiadacze przydzielają stanowiska; może to wskazywać co najwyżej jedno uprawnienie), licence (licencjonowana funkcja, którą musi obejmować licencja organizacji), installation (posiadane wyłącznie przez administratorów danej instalacji) oraz platform (posiadane wyłącznie przez administratorów platformy Adverant; nie wskazuje żadnych ról). Nazwy uprawnień zawierają co najmniej jedną kropkę: project.read, money.pay.
"api": {
"version": "1",
"basePath": "/",
"endpoints": [
{ "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
{ "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
{ "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
{ "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
]
},
"rights": {
"project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
"project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}definePlugin odrzuca trasę w zakresie bez uprawnienia (ENDPOINT_RIGHT_MISSING), uprawnienie, którego brak w rejestrze (ENDPOINT_RIGHT_NOT_REGISTERED), oraz uprawnienie na trasie nieobsługiwanej przez żadnego strażnika (ENDPOINT_RIGHT_UNGUARDED). Odrzuca również rejestr wewnętrznie sprzeczny oraz dwa zapisy tej samej trasy (:id i :recordId) jako DUPLICATE_ENDPOINT.
Dane: databases, schema i db
schema to jedyny schemat Postgres należący do wtyczki. public, plugins, auth i nexus są zabronione, a jeśli databases[] również wskazuje schemat Postgres, oba muszą być zgodne.
databases[] deklaruje każdy magazyn według silnika: postgresql (schema, tables, migrations oraz granted, czyli tabele, które inna organizacja może odczytywać na podstawie zarejestrowanego udzielenia dostępu), neo4j (schemas), qdrant (collections) lub redis (purpose).
db zawiera limity sesji dla każdego połączenia otwieranego przez wtyczkę, zadeklarowane tutaj, a nie w kodzie, aby mogli je odczytać zarówno recenzent, jak i proces wdrożenia:
| Pole | Co ogranicza |
|---|---|
maxConnections |
Pula na replikę |
pods |
Maksymalna liczba podów jednocześnie utrzymujących pulę: repliki plus nadwyżka podczas aktualizacji kroczącej. Limit połączeń każdej roli jest generowany jako maxConnections × pods; w razie pominięcia definePlugin ostrzega DB_PODS_UNDECLARED |
statementTimeoutMs |
Jedna instrukcja |
idleInTransactionTimeoutMs |
Otwarta transakcja, która niczego nie wykonuje |
workMemKB |
Jeden węzeł sortowania lub mieszania, na węzeł, nie na zapytanie |
piiMask[] |
Wpisy table.column zawierające dane osobowe, maskowane w nadzorowanej konsoli SQL i w logach |
Umiejętności i narzędzia: skills, mcpTools, entitlements
skills[] zawiera umiejętności manifestu; rozdział 2.20, Umiejętności, omawia ich pola i poziomy. mcpTools[] zawiera narzędzia MCP (Model Context Protocol) publikowane przez wtyczkę, każde z name, description i inputSchema bez oneOf, allOf ani anyOf na najwyższym poziomie.
entitlements wymaga featureIdPattern i akceptuje alwaysOn[], source oraz store. Wzorzec wskazuje przestrzeń nazw, w której znajdują się identyfikatory funkcji, zwyczajowo name wtyczki plus jeden segment uzupełniany przez kod dla każdego interfejsu. alwaysOn[] to krótka, dokładna lista elementów, które muszą odpowiadać nawet wtedy, gdy nie można uzyskać rozstrzygnięcia o uprawnieniach licencyjnych: kondycja, gotowość, logowanie oraz ustawienia potrzebne administratorowi do naprawy uprawnienia licencyjnego.
Kontrola zmian: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Zatwierdzenia są liczone w odrębnych osobach, a osoba, która zaproponowała zmianę, nigdy nie jest jedną z nich; bez obu tych warunków „dwa zatwierdzenia” stają się jedną osobą klikającą dwukrotnie. enabled: true wymaga classes, a każda wymieniona klasa potrzebuje własnej liczby. Pominięta klasa nie podlega nadzorowi, co jest uprawnionym wyborem, który schemat każe zapisać.
Tożsamość: domains, branding, routing
domains[] (każde z primary i aliases[]; domain to forma dla jednej domeny) wskazuje, gdzie odpowiada wtyczka. branding wymaga appName i akceptuje tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId oraz gaId. Wszystko w branding jest publiczne: strona logowania odczytuje te dane, zanim ktokolwiek uzyska poświadczenie, więc nigdy nie mogą one zawierać sekretu ani adresu wewnętrznego. routing (type, gateway, virtualService) jest przeznaczone dla wtyczek opisujących własny routing.
Wymiarowanie i pozostałe elementy
resources wymaga cpuMillicores (od 10 do 64 000) oraz memoryMB (od 16 do 262 144) i akceptuje diskGB, timeoutMs, port oraz wsPort. backend zawiera port, healthPath, apiPrefix, framework i platformClients[], czyli klientów SDK, które Państwa backend importuje po nazwie. Lista jest zamknięta, a bramka sprawdza ją pod kątem zgodności z Państwa importami. Schemat dopuszcza czternaście nazw: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin i uno, a także jedną dla klienta obsługującego odmowy wynikające z uprawnień planu, który zachowuje nazwę wewnętrzną. Klient uprawnień do funkcji, runtime/entitlements, nie należy do nich i nigdy nie trafia na listę, ponieważ Państwa blok entitlements już go deklaruje, a backend, który go importuje bez bloku entitlements, nie przechodzi tej samej bramki. frontend zawiera basePath, mountPath i framework. nexus zawiera minVersion, maxVersion, capabilities[] i permissions[].
Każdy z pozostałych bloków służy jednemu zadaniu:
| Blok | Przeznaczenie |
|---|---|
settings |
Państwa ustawienia we wspólnym frameworku: groups i keys, ustawiane na poziomach wskazanych przez każde z nich |
people |
sweep (service, port): członkowie organizacji, synchronizowani z usługi tożsamości, z wyłączaniem stanowisk, gdy ktoś odchodzi |
ontology |
entityTypes i relationshipTypes: typowany graf przechowywany w Państwa własnym schemacie |
release |
groups i frame: grupy możliwości, w których etapowane są Państwa trasy, wydawane najpierw jako canary |
cells[] |
Wtyczka składająca się z kilku wdrażalnych komponentów: name, kind, entrypoint, port, wsPort dla każdego |
pricing |
model, currency, tiers[] dla Państwa wpisu w katalogu |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Kto ją publikuje i gdzie znajduje się jej kod |
metrics, atlas |
Dwa celowo otwarte obiekty, na Państwa własne nazwy metryk i generowanie dokumentacji architektury |
Czego schemat nie potrafi wyrazić
JSON Schema określa kształt; definePlugin dodaje reguły, których schemat nie potrafi wyrazić. classification umiejętności nie może przekroczyć pułapu zaufania. Tylko wtyczki core i verified mogą deklarować umiejętności tool_using i llm_only. Każda zadeklarowana ścieżka musi być względna i z tego samego źródła, bez schematu, bez // i bez ukośnika wstecznego, ponieważ parser URL zamienia \ na /, a /\evil.example/x rozwiązuje się do innego źródła. Każda reguła, którą synchronizacja rejestru stosuje do umiejętności, jest najpierw stosowana tutaj, z użyciem kodu samej synchronizacji, dzięki czemu validate i synchronizacja nazywają naruszoną regułę w ten sam sposób.
Walidacja i migracja z wersji v1
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0
Błąd wyświetla dokładną ścieżkę, a w przypadku reguły synchronizacji najpierw kod. Warto ustawić to jako hook commita.
Manifest v1 przenosi się mechanicznie. migrate dodaje trzy zdania prawne, przenosi domain do domains[] i odmawia wymyślenia punktu wejścia, którego Państwo nie mieli. Waliduje wynik przed wyświetleniem lub zapisaniem czegokolwiek, więc migracja nigdy nie przenosi błędu z narzędzia do Państwa repozytorium.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writePrzed zatwierdzeniem proszę przeczytać diff. Dodawane zdania prawne to brzmienie, które przypina walidator; dla własnej instalacji proszę ustawić deploy na zdanie pokazane wcześniej.
Renderowanie dzierżawy (tenancy) i aprowizacja ról
Nigdy nie piszą Państwo ręcznie nadań ról ani szablonu zabezpieczeń na poziomie wierszy. nexus-tenancy render zapisuje je na podstawie schema i db z manifestu:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlWygenerowany plik tworzy pięć ról dla schematu, każdą z określeniem, czego nie może posiadać: migratora, który może jedynie stać się właścicielem, właściciela, który nie może się zalogować, rolę aplikacji dla ścieżki żądań, rolę raportową, która widzi tylko agregaty, oraz rolę rejestru, która może jedynie dopisywać. Żadna rola nie posiada BYPASSRLS. Jedynym sposobem powiązania dzierżawcy jest jedna funkcja bazy danych, a set_config jest odebrane wszystkim rolom poza właścicielem.
Zastosowanego pliku dzierżawy nigdy się nie edytuje. Zmiana jest rewizją z własnym plikiem o numerze 0 i w ten sposób, jako rewizja 2, pojawia się stanowisko odczytu dla nadań między organizacjami. --graph generuje dwie tabele typowanego grafu deklarowanego przez Państwa ontology jako kolejną numerowaną migrację.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sqlPlik dzierżawy tworzy właśnie te role, jako które łączy się runner, dlatego stosuje go właściciel bazy danych za pomocą nexus-migrate provision:
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir><database-owner-url> to ciąg połączenia dla właściciela bazy danych, a <dir> to prywatny katalog. Provision stosuje bazowy plik dzierżawy i każdą rewizję po kolei, zapisuje migrator.url i app.url (oraz seat.url, gdy istnieje rewizja 2) w <dir> z trybem 0600 i nie wyświetla niczego poufnego. Przy każdym uruchomieniu ustawia limit połączeń każdej roli na podstawie db.maxConnections × db.pods. Ponowne uruchomienie zachowuje istniejące hasła, chyba że Państwo zażądają inaczej: --passwords <dir> ustawia je z plików, a --rotate <roles> nadaje wskazanym rolom nowe. Proszę przekształcić te pliki w sekrety swojego wdrożenia.
Następnie stosowanie łączy się za pomocą ciągu połączenia migratora zapisanego przez provision:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonUruchamia pliki od 001 jako migrator, każdy plik w SET ROLE <schema>_owner, jedną transakcję na plik. Prowadzi rejestr, <schema>.schema_migrations, z sumą kontrolną każdego pliku; zastosowany plik, którego bajty się zmieniły, jest odrzucany z nazwy (CHECKSUM_DRIFT), nigdy nie jest ponownie uruchamiany ani pomijany. Każdy oczekujący plik jest parsowany prawdziwą gramatyką Postgres przed uruchomieniem pierwszego, więc odmowa pozostawia bazę danych nietkniętą. Jedynym nagłówkiem, jaki może zawierać plik, jest -- nexus-migration: transaction=file|per-statement, z opcjonalnymi limitami czasu blokady i instrukcji; per-statement służy do CREATE INDEX CONCURRENTLY.
Bramki
nexus-gates uruchamia dwadzieścia dwie bramki. Każda koduje jedną klasę defektów, aby nie mogła zostać wydana dwukrotnie, i każda ma autotest dowodzący, że kończy się niepowodzeniem na fixture zbudowanym tak, by ją wyzwolić. Proszę uruchomić je przed wypchnięciem:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Bramka | Co wykrywa |
|---|---|
scope-adherence |
Trasa /api bez strażnika zakresu; anonimowa ścieżka, która nie jest dokładnie zadeklarowaną; trasa urządzenia bez strażnika urządzenia lub ze strażnikiem osoby obok niego |
one-fence |
Predykat dzierżawcy zdefiniowany gdziekolwiek poza jednym miejscem, w tym ręcznie napisane ogrodzenie stanowiska lub nadania |
sql-fence |
Instrukcja odczytująca lub aktualizująca tabelę objętą zakresem bez ogrodzenia, w dowolnym celu FROM, JOIN, USING lub UPDATE |
migrations-are-scoped |
Tabela bez osi, bez klucza złożonego zaczynającego się od dzierżawcy, bez klucza obcego przenoszącego dzierżawcę lub bez kolumny demo |
migrations-commit-what-they-open |
Migracja, której liczba BEGIN nie zgadza się z liczbą COMMIT i ROLLBACK |
no-direct-compute |
Bezpośrednie wywołanie dostawcy modelu, silnika, kolejki lub hosta przepływów pracy; drugi czytelnik URL dyspozycji |
no-credentials |
Dane uwierzytelniające dostawcy modelu możliwe do odczytania w repozytorium lub środowisku |
crud-adherence |
Trasa modyfikująca, której sprawdzenie prawa nie wskazuje niczego w rejestrze |
blocked-backends |
Trasa, która nie jest ani obsługiwana, ani zablokowana z nazwy, ani odrzucona przez prawo, ani należąca do innego miejsca |
every-test-runs |
Testy, do których nigdy nie dociera glob skryptu testowego |
tiles-are-invariant |
Buforowany styk niezmienny względem dzierżawcy, który odczytuje wartość dzierżawcy lub pomija uwierzytelnianie |
api-contract |
Zarejestrowana trasa, której manifest nie deklaruje, lub zadeklarowana, której kod nigdy nie rejestruje |
rls-present |
Tabela bez wymuszonego zabezpieczenia na poziomie wierszy; funkcja SECURITY DEFINER bez przypiętego search_path |
no-set-config |
Kod wtyczki samodzielnie wiążący ustawienie dzierżawcy |
db-role-honest |
Ścieżka żądania łącząca się jako właściciel lub migrator albo żądająca SUPERUSER lub BYPASSRLS |
platform-clients |
Klient SDK zaimportowany, ale niewymieniony w backend.platformClients, lub wymieniony, ale nigdy niezaimportowany |
rights-register |
Trasa zakresu bez zadeklarowanego prawa; sprawdzenie prawa obok rejestru |
refusal-ledger |
Zadeklarowana tabela odmów bez zainstalowanego rejestru lub treść odmowy wysłana z jego pominięciem |
grants-declared |
Udostępniona tabela, której manifest nie deklaruje; uprawnienia stanowiska odczytu nadawane ręcznie |
people-declared |
Blok people bez trasy czyszczenia, strażnika i tabel |
functions-closure |
Wtyczka Azure Functions, której obsługiwane i zadeklarowane trasy są niezgodne |
declared-input |
Lista parametrów zapytania handlera niezgodna z zadeklarowanym query trasy |
Katalog gates/ zawiera pięć plików wyjątków, które bramka może odczytać (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json i invariant-seams.json), z jednym uzasadnieniem na wpis. Puste uzasadnienie oznacza brak wpisu, a wpis wskazujący coś, co już nie istnieje, powoduje niepowodzenie bramki. Mogą tam Państwo również umieścić własne moduły bramek, a nexus-gates wykryje je obok wbudowanych.
Potok (pipeline) szablonu
Szablon nie zawiera ręcznie napisanego przepływu pracy. Jego konfiguracja potoku wskazuje Dockerfile, jedyny argument kompilacji (token rejestru), próbny przebieg migracji i sondę rozruchu oraz bramkę uruchamianą przez kolejkę scalania. Kolejność odpowiada kolejności, w jakiej chcieliby Państwo, by występowały niepowodzenia.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, czylicreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, czylinexus-gates --self-testnode scripts/ci/required-env
Wokół obrazu działają jeszcze dwa sprawdzenia. Próbny przebieg migracji stosuje każdy plik do jednorazowej instancji Postgres, zanim obraz może zostać wydany, przy użyciu tego samego runnera co produkcja: nexus-migrate provision raz jako superużytkownik, a następnie każdy numerowany plik jako migrator. Sonda rozruchu uruchamia zbudowany obraz z jego własnym punktem wejścia i każdą zmienną wyświetlaną przez required-env, skierowany na zastępniki, które akceptują połączenia i nigdy nie odpowiadają. Serwer czeka na bazę danych w ograniczonym oknie czasowym i to oczekiwanie jest sygnałem powodzenia; loader konfiguracji, który odmawia uruchomienia, powoduje niepowodzenie kompilacji w tym miejscu, a nie w produkcji.
Koszty
SDK odbiera Państwu decyzje, a niektóre z nich podjęliby Państwo inaczej. Manifest odrzuca nieznane klucze, tabela tras musi dokładnie odpowiadać kodowi, role bazy danych nie są do zaprojektowania przez Państwa, a bramki powodują niepowodzenie kompilacji z powodu brakującego prawa przy odczycie. Przy mojej pierwszej wtyczce spędziłem dzień na sporze z api-contract o trasę, którą zarejestrowałem i zapomniałem zadeklarować. Miał rację; trasa nie była chroniona. Proszę się spodziewać, że pierwsza wtyczka będzie powstawać powoli, a druga zajmie jedną trzecią tego czasu.

