Zaloguj sięUmów spotkanie

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

Czas czytania: 22 min

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.0

Przy 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 --write

Przed 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.sql

Wygenerowany 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.sql

Plik 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.json

Uruchamia 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.

Zgodność
Zgodność
Zgodność pokazuje, która wersja SDK działa z którą wersją platformy, na podstawie nocnych uruchomień quickstartu. Nieprzetestowana para jest tak oznaczona, a para kończąca się niepowodzeniem wskazuje zmianę, która ją zepsuła.

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.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, czyli create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, czyli nexus-gates --self-test
  7. node 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.

Tworzenie w edycji Community
Tworzenie w edycji Community
W wersji Community programista otrzymuje te same złote ścieżki, przestrzeń deweloperską i gałęzie danych na jednym serwerze, z kodem we własnym hoście Git. Staging, jednostki pilotażowe i zamaskowane kopie danych produkcyjnych są dostępne w wersji Enterprise.

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.