รุ่น 1.0.0-alpha.1ล่าสุด
บทที่ 2.22
รันไทม์ของปลั๊กอิน
โมดูล SDK (ชุดพัฒนาซอฟต์แวร์) ที่ปลั๊กอินของคุณใช้ทำงาน ตั้งแต่การ์ดควบคุมขอบเขตและรั้วกั้นฐานข้อมูล ไปจนถึงการจ่ายงานของ UNO การอ่านเส้นทาง AI (ปัญญาประดิษฐ์) และการตรวจสอบใบอนุญาต จากนั้นจึงเป็นการทดสอบกับฐานข้อมูลจริง การลงทะเบียนทักษะของคุณ และการเริ่มใช้งาน
หน้านี้แปลโดย AI จากต้นฉบับภาษาอังกฤษ หากมีส่วนใดไม่ชัดเจน โปรดอ้างอิงจากหน้าภาษาอังกฤษ อ่านหน้านี้เป็นภาษาอังกฤษ

ส่วน runtime ของ SDK (software development kit) คือชุดโมดูลภายใต้ @adverant-nexus/plugin-sdk/runtime/* พร้อมตัวช่วยสำหรับการทดสอบภายใต้ testing/* คุณนำเข้าโมดูลเหล่านี้มาใช้ ไม่ต้องเขียนขึ้นใหม่เอง นั่นคือแนวคิดทั้งหมด และผมต้องโดนปฏิเสธในการรีวิวหนึ่งครั้งกว่าจะยอมรับเรื่องนี้อย่างจริงจัง: ความเห็นของผู้รีวิวต่อการตรวจสอบขอบเขตที่ผมเขียนเองในปลั๊กอินแรกมีเพียงบรรทัดเดียว "SDK มีสิ่งนี้อยู่แล้ว และของคุณยอมรับโทเค็น challenge ของ MFA (multi-factor authentication) เป็นเซสชัน"
บทนี้ติดตามคำขอหนึ่งรายการผ่านปลั๊กอินที่กำลังทำงาน ตามวิธีที่เทมเพลต full-service เชื่อมต่อไว้: ตัวป้องกันขอบเขต รั้วฐานข้อมูล การข้ามขอบเขตเพียงหนึ่งเดียวที่อนุญาต การส่งงานผ่าน UNO การอ่านเส้นทาง AI (ปัญญาประดิษฐ์) และการตรวจสอบใบอนุญาต จากนั้นจึงกล่าวถึงการทดสอบ การลงทะเบียนสกิลใน manifest ของคุณ และขั้นตอนการเริ่มต้นใช้งาน
ขอบเขต: หนึ่งการ์ดต่อหนึ่งเฟรมเวิร์ก
ทุกเส้นทาง /api มีตัวป้องกันขอบเขต ตัวป้องกันนี้จะตรวจสอบ bearer token ระบุสามแกน (tenant, owner, unit) จากโทเค็นนั้น ปฏิเสธเนื้อหาคำขอที่ระบุ tenant ใช้สิทธิ์ของเส้นทางจากทะเบียนของ manifest และหลังจากนั้นเท่านั้นจึงปล่อยให้ handler ทำงาน SDK มีอะแดปเตอร์หนึ่งตัวต่อหนึ่งเฟรมเวิร์ก ทั้งหมดมาจาก @adverant-nexus/plugin-sdk/runtime/scope และทั้งหมดรับตัวเลือกชุดเดียวกัน
| เฟรมเวิร์ก | อะแดปเตอร์ |
|---|---|
| Express | scopeMiddleware |
| Fastify | requireScope ในฐานะ preHandler |
| ถัดไป | withScope ครอบ handler ไว้ เนื่องจาก handler ของ Next ไม่ได้รับแจ้งเส้นทางของตน withScope จึงรับเส้นทางเป็นอาร์กิวเมนต์ที่สาม |
ต่อไปนี้คือการเชื่อมต่อ Express ของเทมเพลตแบบย่อ ตัวตรวจสอบเป็นของ SDK และบังคับให้โทเค็นเป็นไปตามรูปแบบเซสชันของบริการระบุตัวตน: HS256 เท่านั้น ต้องมี iss, exp, iat และ jti อายุการใช้งานไม่เกินหนึ่งชั่วโมง และไม่ยอมรับโทเค็น challenge ของ 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 และไม่มี seat ใดยกเลิกการปฏิเสธนี้ได้ บทบาทที่อยู่ใน roles จะได้รับอนุญาต โดยต้องมี seat ที่ใช้งานอยู่ด้วยเมื่อสิทธิ์ระบุ seat: true มิฉะนั้น seat ที่ใช้งานอยู่ซึ่งมีสิทธิ์นั้นจะได้รับอนุญาต มิฉะนั้นคำขอจะถูกปฏิเสธ AUTHORITY_EXCEEDED โดยระบุชื่อบุคคลที่สามารถมอบ seat ได้ หากคุณให้ store (rights: { manifest, store: { pool, schema } }) แก่ตัวป้องกัน ตัวป้องกันจะอ่าน seat ภายใต้ขอบเขตของผู้เรียกเอง สิทธิ์ที่ระบุ licence จำเป็นต้องมีตัวอ่านใบอนุญาตด้วย ซึ่งจะกล่าวถึงด้านล่าง
ภายใน handler scopeOf(req) เป็นวิธีเดียวในการอ่านขอบเขตที่ระบุแล้ว และจะ throw หากตัวป้องกันไม่ได้ทำงาน ตัวป้องกันที่ลงทะเบียนบน prefix ซึ่งทำงานก่อนที่เส้นทางใดจะจับคู่ได้ จะตอบ 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 สำหรับโทเค็นแบบลงนามรายการเรียกของแพลตฟอร์ม SDK มี requireService (Fastify) และ serviceMiddleware (Express) ซึ่งตรวจสอบด้วยว่าโทเค็นถูกออกให้สำหรับสกิลและเส้นทางใด และปฏิเสธโทเค็นที่ถูกใช้ซ้ำ
รั้วฐานข้อมูล: 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 สำหรับตารางส่วนบุคคล และละไว้สำหรับอาร์ติแฟกต์ขององค์กรที่ owner เป็นเพียงข้อมูลที่มา เมื่อคำสั่งมีพารามิเตอร์อยู่แล้ว startIndex จะบอกรั้วว่าควรเริ่มนับลำดับจากตำแหน่งใด การ insert จะไม่รับแกนเป็นอินพุต แต่จะเขียน scope.tenant, scope.owner และ scope.unit จากขอบเขต
withScopedTx ผูกทั้งสามแกนสำหรับธุรกรรมหนึ่งรายการผ่านฟังก์ชันผูกเพียงหนึ่งเดียวของ schema แล้วจึงเรียก callback ของคุณ การผูกครั้งที่สองในธุรกรรมเดียวกันจะเกิด SCOPE_ALREADY_BOUND (500: โค้ดของคุณผูกซ้ำ ผู้เรียกไม่ได้ทำผิด) tenant หรือ owner ที่ไม่มีหรือเป็นศูนย์จะเกิด SCOPE_PREDICATE_INVALID (403) การตั้งค่านี้มีผลเฉพาะภายในธุรกรรม ดังนั้นการเชื่อมต่อจาก pool จึงไม่สามารถนำ tenant หนึ่งไปยังคำขอถัดไปได้
ฟังก์ชันพี่น้องอีกสองตัวครอบคลุมกรณีที่ไม่ใช่คำขอของบุคคล withTenantScopedTx ผูก tenant และ unit โดยไม่มี owner สำหรับแถวที่เครื่องอ่าน (ทะเบียนอุปกรณ์) และปฏิเสธขอบเขตที่มี owner maintenanceScope(reason) บังคับให้การดำเนินการระดับทั้งองค์กรประกาศอย่างชัดเจนว่าตนคืออะไร ก่อนที่ธุรกรรมของ owner จะเปิดได้ รั้วในโค้ดและการบังคับใช้ row-level security เป็นสองกลไกสำหรับกฎข้อเดียวกัน การตรวจสอบตอนบูตจะปฏิเสธการรับฟังจนกว่าฐานข้อมูลจะพิสูจน์ได้ว่ากลไกที่สองมีผล (มิฉะนั้นจะเกิด DB_ROLE_BYPASSES_ISOLATION)
ทุกการปฏิเสธจะถูกบันทึกเป็นหนึ่งแถว
เทมเพลตติดตั้ง middleware อีกหนึ่งชิ้น เพียงครั้งเดียว ระหว่างตัวแยกวิเคราะห์เนื้อหาคำขอกับ router: บัญชีบันทึกการปฏิเสธ
import { recordRefusals } from "@adverant-nexus/plugin-sdk/runtime/refusal-ledger";
app.use(express.json({ limit: "256kb" }));
app.use(recordRefusals({ pool, schema: SCHEMA }));middleware นี้ครอบการตอบกลับ เพื่อให้การปฏิเสธทุกครั้งที่บุคคลได้รับ ไม่ว่าจะมาจากตัวป้องกันสิทธิ์ handler หรือ store ถูกเขียนลงในตาราง refusal ของ schema ของคุณภายในธุรกรรมที่มีขอบเขตของบุคคลนั้นเอง ก่อนที่เนื้อหาการตอบกลับจะถูกส่ง 401 แบบไม่ระบุตัวตนจะไม่เขียนสิ่งใด หากไม่สามารถเขียนแถวได้ คำตอบจะกลายเป็น UNHANDLED_ERROR: คำว่า "ไม่" ที่ผลิตภัณฑ์บันทึกไม่ได้จะไม่ถูกส่งออกไปราวกับว่าบันทึกได้ ตอนบูตจะเรียก assertRefusalLedger เพื่อตรวจสอบว่าตารางรับแถวของบัญชีบันทึกได้ และ store สามารถเรียก noteSubject({ recordId, isDemo }) เพื่อให้การปฏิเสธทุกครั้งระบุเรกคอร์ดที่เกี่ยวข้อง เมื่อลูกค้าถามว่าเหตุใดจึงมีคนถูกปฏิเสธเมื่อวันอังคารที่แล้ว คำตอบคือการคิวรี ไม่ใช่การคาดเดา
การข้ามขอบเขตเพียงหนึ่งเดียว: การอนุญาตแบบอ่านอย่างเดียวที่มีการบันทึกไว้
เมื่อลูกค้ารายหนึ่งของคุณทำงานให้กับอีกรายหนึ่ง และอีกรายหนึ่งอาจตรวจสอบงานนั้น มีวิธีที่ได้รับอนุมัติเพียงวิธีเดียวในการข้ามขอบเขต องค์กรที่ถือแถวข้อมูลจะบันทึกการให้สิทธิ์ องค์กรของผู้อ่านจะอนุญาตบุคคลผ่าน seat ที่มีสิทธิ์ granted.read ซึ่งต้องระบุ owner และ admin ใน never การอ่านจะทำงานในฐานะบทบาทฐานข้อมูลที่หก คือ read seat ซึ่ง select ได้เฉพาะตารางที่ 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 ของผู้อ่านเองก่อน จากนั้นผูก read seat เข้ากับการให้สิทธิ์ ซึ่งจะเขียนบันทึกการเข้าดูใน tenant ของผู้ถือข้อมูล นโยบายของฐานข้อมูลเองจะตรวจสอบว่าการให้สิทธิ์ระบุองค์กรของผู้อ่าน ครอบคลุมตาราง เริ่มมีผลแล้ว ยังไม่สิ้นสุด และไม่ถูกเพิกถอน และธุรกรรมนี้ได้เขียนบันทึกการเข้าดูแล้ว การอ่านที่ข้ามการบันทึกการเข้าดูจะไม่เห็นข้อมูลใดเลย ตอนบูต assertSeatAtBoot(seatPool, schema) จะตรวจสอบว่า pool ที่เปิดจาก seat.url เป็น seat นั้นจริงและไม่มีสิ่งใดเกินกว่านั้น และปฏิเสธด้วย 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 คอมไพล์ออกมาทุกประการ
Envelope
การส่งงานมีหกฟิลด์เป็นแกนหลักที่จำเป็น ไคลเอนต์จะเติม tenant และ actor จากขอบเขตที่ตรวจสอบแล้ว ไม่ใช่จากคำขอ:
| ฟิลด์ | ข้อมูลที่เก็บ |
|---|---|
jobType |
ประเภทงานแบบมี namespace <plugin name>.<skill id> |
organizationId |
tenant จากขอบเขต |
userId |
actor จากขอบเขต สำหรับการตรวจสอบย้อนหลังและการเรียกเก็บเงิน |
inputParams |
อินพุตของสกิล ซึ่งไม่มี tenant id เด็ดขาด อินพุตที่มีจะถูกปฏิเสธตอนส่งงาน |
priority |
critical, high, normal หรือ low |
pluginId |
name ใน manifest ของคุณ การส่งงานทุกครั้งต้องประกาศปลั๊กอินต้นทาง |
ฟิลด์ที่ไม่บังคับได้แก่ correlationId (UUID (universally unique identifier) หรือจะสร้างขึ้นใหม่) และ 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 แล้วจึงโพลล์
การส่งงานทุกครั้งจะถูกเข้าคิว คำตอบจะเป็น 202 พร้อมตัวระบุ (jobId, runId, traceId, status) เสมอ ไม่ใช่ผลลัพธ์ ผลลัพธ์มาจากการโพลล์งานหรือจาก callback ของคุณ uno.peek(jobId, { scope }) อ่านผลหนึ่งครั้ง และ awaitJob โพลล์จนถึงสถานะสิ้นสุด ทั้งสองส่ง 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 และผู้เรียกในฐานะ actor และการตัดสินโดยบุคคลอื่นที่ไม่ใช่ผู้เรียกที่ตรวจสอบแล้วจะถูกปฏิเสธ การอนุมัติจะปล่อยงานหนึ่งครั้งและเรียกใช้การตรวจสอบการส่งงานอีกครั้ง การปฏิเสธจะสิ้นสุดงาน failed การตัดสินครั้งที่สองจะถูกปฏิเสธ เช่นเดียวกับการตัดสินหลังจากการพักหมดอายุ หากผลิตภัณฑ์ของคุณต้องการให้ผู้อนุมัติเป็นคนละคนกับผู้เสนอ ให้บังคับใช้ในเส้นทางที่ทำการตัดสิน: แพลตฟอร์มบันทึกทั้งสองคน
แสดงงานที่ถูกพักว่าเป็นงานที่ถูกพัก อย่าบอกบุคคลว่าการคลิกของเขาปล่อยงานแล้ว จนกว่าแถวการรันจะระบุเช่นนั้น
AI: ความต้องการ (Wishes) บนแถวข้อมูลทักษะ และการอ่านเพียงครั้งเดียว
ปลั๊กอินของคุณไม่เรียกโมเดลโดยตรงเลย เมื่อสกิลใน 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 รับที่อยู่ของ gateway, bearer ของผู้เรียกเอง และ slug ของแพลตฟอร์มของคุณ และไม่ส่งคำขอ AI ใด ๆ คำตอบประกอบด้วยผู้ให้บริการและโมเดล ผู้ให้บริการที่นโยบายอนุญาต และ endpoint ที่เลือกทำงานแบบ local หรือ external เมื่อใช้เส้นทางไม่ได้ จะตอบด้วยการปฏิเสธของ router เป็นข้อความ (NO_PROVIDER_FOR_ROLE, MODEL_CAPABILITY_UNAVAILABLE หรือ NO_MODEL_FOR_ROLE_AND_PROVIDER พร้อมวิธีแก้ไข) ไม่ใช่โมเดลเริ่มต้น แสดงการปฏิเสธนั้นแก่บุคคล เพราะเป็นการกำหนดค่าขององค์กรของเขาเอง
การตรวจสอบใบอนุญาต
มีกลไกสามอย่างที่ตรวจสอบใบอนุญาต ในสามระดับความละเอียด
สิทธิ์ที่ระบุใบอนุญาต วิธีที่ง่ายที่สุด ใน manifest สิทธิ์จะมี licence: "<feature>" และตัวป้องกันจะสอบถามบริการระบุตัวตนว่าใบอนุญาตขององค์กรมีฟีเจอร์นั้นหรือไม่ ด้วยโทเค็นของผู้เรียกเอง ก่อนที่จะอ่านบทบาทใด ๆ สร้างตัวป้องกันพร้อมตัวอ่าน:
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 และประตูจะไม่ถือว่ากรณีหนึ่งเป็นอีกกรณีหนึ่งเด็ดขาด
ตัวเอกสารใบอนุญาตเอง โค้ดที่ต้องตัดสินใจเองจากใบอนุญาตที่ลงนาม เช่น โมดูลปิดของ domain pack ใช้ verifyLicenceDocument(docText, opts) จาก runtime/licence-document เป็นฟังก์ชันบริสุทธิ์: ไม่มีการเรียกผ่านเครือข่าย ไม่มีตัวแปรสภาพแวดล้อม ไม่มีไฟล์ ฟังก์ชันจะตรวจสอบลายเซ็นทั้งสองเทียบกับ trust root ที่ build มีอยู่ และตอบสถานะ (VALID, WARN, GRACE, RESTRICT, TERMINATE หรือ ABSENT) พร้อมสิทธิ์ที่ได้รับ ส่วนเสริม และ domain pack จากนั้น licenceAllows(verdict, featureGroup, action, tenantId?) จะบอกว่าคุณสามารถ use หรือ provision ภายใต้กลุ่มได้หรือไม่ RESTRICT อนุญาต use และตอบ provision ด้วย LICENCE_LOCKED ดังนั้นงานที่กำลังทำงานอยู่จะดำเนินต่อไป และไม่มีงานใหม่เริ่มขึ้น
การทดสอบ
การทดสอบของเทมเพลตแสดงรูปแบบไว้ ต่อไปนี้คือเครื่องมือเบื้องหลังรูปแบบนั้น
ขอบเขตจำลอง สร้างตัวจำลองขอบเขตที่ระบุแล้วเพียงครั้งเดียวใน test/scope-fakes.ts และฉีดเข้าไปทุกที่ รวมถึงกรณีที่ขาดหาย: ไม่มี unit ไม่มีโทเค็น โทเค็นที่มีองค์กรเป็นศูนย์ เส้นทางการปฏิเสธคือตัวผลิตภัณฑ์
transport การส่งงานจำลอง UnoClient รับ fetch, now และ sleep ดังนั้นการทดสอบหน่วยจะไม่แตะเครือข่ายเลย ให้ยืนยันฟิลด์ของ envelope รูปแบบของ 202 การโพลล์จนถึงแถวสถานะสิ้นสุดพร้อม 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 (continuous integration) เครื่องที่ไม่มีเซิร์ฟเวอร์ Postgres จะข้ามกรณีทดสอบฐานข้อมูลแต่ละกรณีโดยระบุชื่อพร้อมวิธีแก้ไข และจะไม่แสดงผลเป็นผ่าน ใน CI การไม่มีเซิร์ฟเวอร์แบบเดียวกันจะทำให้ชุดทดสอบล้มเหลว (EPHEMERAL_POSTGRES_UNAVAILABLE_IN_CI) เพราะการทดสอบความปลอดภัยระดับแถวที่ถูกข้ามคือด่านตรวจที่แสดงผลผ่านโดยไม่ได้วัดสิ่งใดเลย เซิร์ฟเวอร์จะรอเริ่มทำงานได้นานสูงสุด 180 วินาที และตัวเฝ้าระวัง (watchdog) จะหยุดเซิร์ฟเวอร์เมื่อโปรเซสทดสอบสิ้นสุดลง
ชุดทดสอบการแยกข้อมูล runIsolationHarness(target) จาก testing/isolation-harness จะอ่านทุกเส้นทาง (route) ที่แอปของคุณเมานต์ และโจมตีแต่ละเส้นทางในฐานะผู้ดูแลระบบขององค์กรอื่นและในฐานะเพื่อนร่วมงาน จากนั้นจะโจมตีอีกครั้งโดยถอดรั้วป้องกันในโค้ดออก ถอดรั้วป้องกันในฐานข้อมูลออก และถอดทั้งสองอย่าง เส้นทางจะเป็น PROVEN ก็ต่อเมื่อการโจมตีล้มเหลวเมื่อมีรั้วป้องกันอย่างใดอย่างหนึ่งอยู่ และเข้าถึงข้อมูลของเหยื่อได้เมื่อถอดทั้งสองอย่างออก ดังนั้นคุณจึงมั่นใจได้ว่าการทดสอบสามารถตรวจพบการรั่วไหลได้จริง ระบบจะส่งคิวรีและเนื้อหาตัวอย่างที่ประกาศไว้ของแต่ละเส้นทาง เพื่อให้เส้นทางที่ปฏิเสธคำขอว่างยังคงถูกเข้าถึงได้ ตรึง ledgerOf(report) ไว้ในการทดสอบ และให้ล้มเหลวเมื่อพบ defectsOf(report)
การลงทะเบียน: จาก Manifest ไปสู่รีจิสทรีของทักษะ
สกิลในแมนิเฟสต์ของคุณจะเข้าสู่รีจิสทรีสกิลผ่านเส้นทางเดียว:
manifest.skills[] → compileRegistry(manifest) → POST /api/v1/plugins/sync
compileRegistry จะแปลงแมนิเฟสต์ที่ผ่านการตรวจสอบแล้วให้เป็นเนื้อหา nexus.plugin-sync/v1 เทมเพลตจะทำขั้นตอนนี้ตอนนำเข้า ดังนั้นแมนิเฟสต์ที่ไม่ถูกต้องจะทำให้การบิลด์ล้มเหลว:
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" } ]
}การซิงก์เป็นแบบประกาศ (declarative): ส่งชุดสกิลทั้งหมดทุกครั้ง และสกิลที่ไม่ได้ส่งมาจะถูกปิดใช้งานโดยยังเก็บประวัติไว้ การซิงก์มีความเข้มงวด: ฟิลด์ที่ไม่รู้จัก ฟิลด์ของระดับชั้นอื่น หรือ null จะถูกปฏิเสธ การละเมิดทั้งหมดจะถูกส่งกลับมาพร้อมกันใน 400 SYNC_CONTRACT_VIOLATION เดียว และจะไม่มีการเขียนข้อมูลใด ๆ ขณะที่ยังมีการละเมิดอยู่ และระบบจะเขียนรีจิสทรีหนึ่งแถวต่อหนึ่งสกิล โดยใช้ประเภทงานที่มีเนมสเปซเป็นคีย์ พร้อมทุกคอลัมน์ที่ตัวจัดส่งงาน (dispatcher) อ่าน ดังนั้นสกิลจะพร้อมรันได้ทันทีที่การซิงก์ตอบกลับ 200
ปลั๊กอินคือผู้เรียกที่ผ่านการยืนยันตัวตน ไม่ใช่ฟิลด์ในเนื้อหา ให้เรียกการซิงก์จากเวิร์กโหลดของปลั๊กอินเองผ่าน mTLS (mutual 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)
การเริ่มต้นใช้งาน (onboarding) ทำงานเป็นสิบขั้นตอนตามลำดับ โดยแต่ละขั้นตอนสามารถรันซ้ำ ยกเลิก หรือย้อนกลับได้โดยอิสระ:
- โคลนรีโพซิทอรีและตรวจสอบความถูกต้อง
- แยกวิเคราะห์แมนิเฟสต์
- สแกนหาปัญหาด้านความปลอดภัย
- บิลด์อิมเมจ
- พุชอิมเมจไปยังรีจิสทรีของการติดตั้ง
- ตั้งค่าชื่อโดเมน
- ดีพลอยผ่านช่องทางรีลีสของการติดตั้ง
- รอการตรวจสอบสถานะ (health check)
- ลงทะเบียนปลั๊กอิน
- แจ้งนักพัฒนา
ก่อนการดีพลอย การตรวจสอบความสอดคล้องห้ารายการจะทำงานกับแมนิเฟสต์และอิมเมจที่บิลด์แล้ว ได้แก่ แมนิเฟสต์แยกวิเคราะห์ได้และมีฟิลด์ที่จำเป็นครบ ทุกเส้นทางที่ประกาศไว้เป็นเส้นทางที่ลงทะเบียนจริง ปลั๊กอินเป็นเจ้าของสคีมาของตนเองและไม่เขียนข้อมูลใด ๆ นอกสคีมานั้น มีการประกาศคำขอทรัพยากรและอยู่ภายในขอบเขต และอิมเมจมีตัวจัดการ health ที่ทำงานได้ ปลั๊กอินที่ลงทะเบียนตนเองตอนบูตจะรันสัญญาเดียวกันภายใต้สิทธิ์ของตนเอง ดังนั้นการตรวจสอบเหล่านี้จึงกลายเป็น CI ของปลั๊กอินแทนที่จะเป็นของไปป์ไลน์ การข้ามรายการใดรายการหนึ่งไม่ได้ทำให้การเริ่มต้นใช้งานสั้นลง แต่จะย้ายความล้มเหลวไปเกิดตอนรันไทม์
แบรนดิงในแมนิเฟสต์ของคุณจะถูกให้บริการโดยไม่ต้องยืนยันตัวตนตามโดเมน เพราะหน้าลงชื่อเข้าใช้ต้องใช้ข้อมูลนี้ก่อนที่ใครจะมีข้อมูลประจำตัว ให้ถือว่าทุกอย่างใน branding เป็นข้อมูลสาธารณะ
GATE_CANNOT_BE_SKIPPEDสิ่งที่รันไทม์จะไม่ทำให้คุณ
รันไทม์รักษามาตรฐานด้านการแยกข้อมูล การจัดส่งงาน และการเข้าถึงโมเดล แต่จะไม่ทำให้ตรรกะผลิตภัณฑ์ของคุณถูกต้อง และจะไม่ทำให้คิวรีที่ช้าเร็วขึ้น ทุกคำสั่งจะรันภายในทรานแซกชันที่มีขอบเขต โดยใช้ค่าหมดเวลาที่บล็อก db ในแมนิเฟสต์ของคุณประกาศไว้ และคำสั่งที่ใช้เวลาเกิน statementTimeoutMs จะถูกยกเลิก ไม่ใช่รอ ให้ออกแบบขนาดคิวรีของคุณให้สอดคล้องกับข้อนี้ นอกจากนี้ การระงับเพื่อรออนุมัติ ที่นั่งสำหรับการอ่าน และตัวอ่านใบอนุญาต ล้วนเพิ่มการเดินทางไปกลับหรือทรานแซกชันหนึ่งครั้ง ในปลั๊กอินตรวจทานความผิดปกติของผม การตรวจสอบใบอนุญาตเพิ่มเวลาไม่กี่มิลลิวินาทีต่อคำขอจนกว่าหน่วยความจำ 30 วินาทีของมันจะพร้อมใช้งาน ซึ่งเป็นราคาที่สมเหตุสมผลสำหรับการไม่ให้บริการฟีเจอร์ที่ถูกล็อกเลย

