Communitygithub.com

Adrian7373/semantischer-Videopipeline

Wird beim Bereitstellen oder Verwalten einer App mit Prisma Composer (`@prisma/composer`) verwendet: Verdrahtung seiner Dienste und Module, lokales Ausführen, Testen komponierter Dienste oder Auf-/Abbau einer Umgebung. Ausgelöst durch 'prisma composer', '@prisma/composer', 'prisma app', `prisma deploy`, `prisma dev`, `compute()`, `module()`, `contract()`, `service.load()`, `mockService`, `bootstrapService`.

Was ist semantischer-Videopipeline?

Diese Skill-Anleitung beschreibt die Kernkonzepte von Prisma Composer, einem Framework zum Definieren und Bereitstellen von Prisma-Apps als typisierte Deklarationsbäume in TypeScript. Sie behandelt die drei Knotentypen (Service, Ressource, Modul), die über typisierte Ports verdrahtet werden, und betont, dass die Kompilierzeitprüfung (`tsc`) die Korrektheit der Verdrahtung sicherstellt, nicht die Cloud-Bereitstellung. Die Anleitung erklärt, wie Runtime-Code Abhängigkeiten, Konfiguration und Geheimnisse ausschließlich über den Service-Knoten (`service.load()`, `service.input()`, `service.port()`) erhält, und nicht über `process.env`. Sie behandelt auch wichtige Themen wie Builds (separat für jeden Dienst), Datenbankmigrationen (nur Replay), RPC über HTTP mit automatischer Idempotenz und Wiederholungslogik sowie die Bereitstellungskonfiguration über `prisma.config.ts`. Die Skill-Anleitung richtet sich an Entwickler, die Composer verwenden, und dient als stabiles konzeptionelles Kernstück, während die aktuelle vollständige Dokumentation unter https://www.prisma.io/docs zu finden ist.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-composer-core-concepts

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Prisma Composer Kernkonzepte

Eine Prisma App ist ein Baum aus typisierten Deklarationen, die in TypeScript zusammengestellt und an die prisma CLI übergeben werden, welche zwei Composer-Befehle hat: prisma deploy und prisma dev. Das Abreißen und die Protokolle sind keine Befehle; sie sind die destroy- und log-Operationen von @prisma/composer/control, die aus einem Skript aufgerufen werden. Diese Datei behandelt Strukturen, Hierarchien, Beziehungen und Arbeitsabläufe: die Konzepte, die Sie weder im Code noch in der CLI-Hilfeausgabe beobachten können. Es ist keine CLI-Referenz; entdecken Sie die Flags jedes Befehls mit prisma <command> --help, anstatt sie zu erraten. Die Prisma-Plattform bewegt sich schnell, behandeln Sie diese Datei daher als stabiles konzeptionelles Kernstück und finden Sie aktuelle, ausführlichere Dokumentation unter https://www.prisma.io/docs. Für funktionierenden Code lesen Sie examples/ im prisma/composer-Repository.

Zwei Prinzipien regieren alles und sind verbindlich (docs/design/01-principles/):

  1. Ihr Code liest nie seine Umgebung. Abhängigkeiten, Konfiguration, Anmeldeinformationen und der Port treffen alle über den Service-Knoten ein, typisiert. process.env ist nie die Antwort.
  2. Composer bündelt oder transformiert Ihren Code nie. Sie bauen mit Ihrem eigenen Bundler; das Framework setzt die erstellte Ausgabe durch deterministische Schritte zusammen und übergibt sie an das konfigurierte Bereitstellungsziel.

Deklarationen sind Daten

Alles, was Sie erstellen, ist eine Deklaration: einfache Daten, die ein Stück der App beschreiben und beim Importieren nichts ausführen. Es gibt drei Knotenarten:

ArtDeklariert mitZweck
Servicecompute()Eine laufende Einheit Ihres Codes; atomar, Composer sieht nur seine Ports
RessourcerawPostgres(), bucket()Eine zustandsbehaftete verwaltete Abhängigkeit
Modulmodule()Eine Gruppierungsgrenze; führt keinen eigenen Code aus, stellt typisierte Ports bereit

Knoten werden über Ports verbunden: deps deklariert, was ein Knoten benötigt, expose deklariert, was er anbietet. Die Verdrahtung erfolgt im Builder eines Moduls über provision(), und das Stamm-Modul, das an die CLI übergeben wird, ist die App:

// module.ts
import { module } from '@prisma/composer';

export default module('store', ({ provision }) => {
  const catalog = provision(catalogModule);
  provision(storefrontService, { deps: { catalog: catalog.rpc } });
});

Da Ports typisiert sind, überprüft der Compiler jede Verdrahtung. Eine Abhängigkeit, die mit dem falschen Produzenten verdrahtet ist, ein fehlender RPC-Handler, ein Literaleingabewert der falschen Form: All dies schlägt bei tsc fehl, nicht bei der Bereitstellung. Umgebungsgebundene Eingabe ist die Ausnahme: Diese Werte existieren nur bei der Bereitstellung, daher tauchen Geheimnis-Bindungs-Konflikte und fehlende Plattformvariablen stattdessen als frühzeitige Bereitstellungsverweigerungen auf (siehe Zwei Kanäle unten). Typprüfung, dann Build, dann Bereitstellung; verwenden Sie die Cloud nicht, um herauszufinden, ob die Verdrahtung korrekt ist.

Composer selbst ist zielagnostisch: @prisma/composer enthält das Erstellen, Testen und die CLI, gekoppelt an keine Plattform. Ein Bereitstellungsziel ist eine Erweiterung, die in der Bereitstellungskonfiguration registriert ist; @prisma/composer-prisma-cloud ist das Prisma Cloud-Ziel und dasjenige, das die Bereitstellungsabschnitte dieser Skill-Anleitung annehmen. Seine Wurzel exportiert compute, rawPostgres, bucket, envSecret und envParam; das ORM-Vokabular (postgres, dataContract) lebt unter dem Unterpfad /orm, zusammen mit den gemeinsamen Modulen /cron, /storage, /streams, /auth und /email. Dies sind die einzigen beiden Composer-Pakete, die eine grundlegende Prisma Cloud-App benötigt, und nichts installiert sie für Sie: Ein neues Projekt beginnt mit keinem von beiden, fügen Sie also beide zuerst als Abhängigkeiten hinzu. Eine Erweiterung fügt ihr eigenes prisma-composer-*-Paket neben ihnen hinzu. Komponieren Sie ein vorhandenes Modul, bevor Sie eine Fähigkeit selbst implementieren; das Verdrahten eines solchen ist ein paar Zeilen.

Innerhalb des Entry-Graphen (alles, was von module.ts aus erreichbar ist), schreiben Sie relative Importe mit expliziten .ts-Erweiterungen (./service.ts, mit allowImportingTsExtensions in tsconfig): Diese Form wird überall aufgelöst. prisma deploy und prisma dev bilden auch ./service.js und erweiterungsloses ./service auf die .ts-Quelle ab, aber andere Tools möglicherweise nicht.

Der Service-Knoten ist die einzige Tür

Ihr Runtime-Code erhält alles von der Service-Deklaration, die er importiert:

  1. service.load(): Abhängigkeiten (typisierte RPC-Clients, Datenbankbindungen).
  2. service.input(): die gesamte Eingabe als ein schema-validiertes Objekt; darin enthaltene Anmeldeinformationen sind SecretString-Boxen, die geschwärzt werden.
  3. service.port(): der reservierte Port zum Binden (Standard 3000).

Eine Service-Deklaration sind reine Daten; der Server-Eintrag ist das, was Ihr Build produziert und die Plattform bootet:

// service.ts
export default compute({
  name: 'auth',
  deps: { db: rawPostgres() },
  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
  expose: { rpc: authContract },
});

// server.ts
const { db } = service.load(); // { url }: Sie konstruieren Ihren eigenen Client
const handler = serve(service, {
  rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });

Der Verbraucher deklariert deps: { auth: rpc(authContract) } und erhält einen typisierten Client von load() zurück.

Zwei Kanäle: Abhängigkeiten und Eingabe

Der Wert ist…DeklarierenBereitstellenLesen
von einem anderen Knoten erzeugtdeps: { db: rawPostgres() }bei provision() verdrahtenload()
alles andere (Konfiguration oder Geheimnis)ein Feld des input-Schemasbei provision() binden: Literal, envParam() oder envSecret()input()

Der Service deklariert seine gesamte eingehende Konfiguration, einfache Werte und Geheimnisse zusammen, als ein Standard Schema (arktype ist die hauseigene Wahl). Ein Geheimnis ist ein Feld, das als secretString() von @prisma/composer/arktype typisiert ist; bedingte Legalität ("kein Stripe-Schlüssel, es sei denn, die Abrechnung ist aktiviert") ist eine gewöhnliche Schema-Vereinigung. Die Bindung bei provision() spiegelt die Form des Schemas wider; envSecret('NAME') benennt die Plattformvariable und trägt niemals den Wert.

Regeln, die beißen:

  1. Geheimnishaftigkeit wird durch Validierung erzwungen. Ein Literal, das gebunden ist, wo das Schema SecretString erwartet, führt zum Fehlschlagen der Bereitstellung; envSecret, das an ein einfaches Zeichenfolgenfeld gebunden ist, schlägt auf die gleiche Weise fehl.
  2. envParam-Werte kommen als rohe Zeichenfolgen an; binden Sie sie an Zeichenfolgenfelder. Die Plattformvariable der Stufe ist der Speicher; die bereitstellende Shell sät nur einen fehlenden Namen ein (und die Bereitstellung schlägt früh fehl, benennt die Variable, wenn beide fehlen). Das Ändern des Plattformwerts erfordert eine erneute Bereitstellung.
  3. Abwesenheit ist die Entscheidung des Schemas. Ein umgebungsgebundenes Feld, dessen Variable nicht gesetzt oder leer ist, löst sich zu Schlüssel ausgelassen auf, was nur legal ist, wenn das Schema es zulässt (optionales Feld, Vereinigungsarm). Der Bereitstellungsbericht druckt das serialisierte Eingabedokument (Geheimnisse reiten als {"$secret":"VAR"}-Zeiger) und jeden Schlüssel, der sich als abwesend aufgelöst hat.
  4. Der reservierte port liegt außerhalb des Schemas. Lesen Sie ihn über service.port(), niemals process.env. Das Framework exportiert auch PORT für Next.js standalone, das ihn selbst bindet.
  5. Ein Modul leitet einen Geheimnisbedarf weiter, ohne den Plattformnamen zu lernen. Deklarieren Sie secrets: { signingKey: secret() } an der Modulgrenze und übergeben Sie die weitergeleitete Referenz als ein Bindungsblatt; das übergeordnete Element bindet die echte Quelle.
  6. input.apiKey.expose() ist der einzige Weg zum Wert eines Geheimnisses; die Box schwärzt überall sonst (Protokolle, JSON, Fehler).

Verträge und RPC

Ein Vertrag ist die typisierte Schnittstelle, über die Dienste kommunizieren. Er lebt bei dem Dienst, der ihn besitzt, typisiert durch einen beliebigen Standard-Schema-Validator, und sowohl Anbieter (serve(), zur Kompilierzeit erschöpfend über die Methoden des Vertrags) als auch Verbraucher (rpc(contract)) referenzieren denselben Wert. Aufrufe reisen als RPC über HTTP. Zwei Verhaltensweisen werden für Sie bereitgestellt und dürfen nicht neu implementiert werden:

  1. Service-Schlüssel. Bei der Bereitstellung prägt Composer einen eindeutigen, unerratbaren Schlüssel pro Verbraucher→Anbieter-Bindung; serve() gibt 401 an alles andere zurück, bevor der Handler läuft. Nichts in Ihrem Code deklariert ihn. Konsequenzen: Bauen Sie keine eigene Service-zu-Service-Authentifizierung und verwenden Sie kein curl auf ein bereitgestelltes /rpc/<method>, um zu überprüfen, ob es funktioniert. Ein unverdrahteter Aufrufer erhält immer 401, was wie eine kaputte Bereitstellung aussieht und es nicht ist. Debuggen Sie über einen Verbraucher oder lokal, wo nichts erzwungen wird. Schlüssel sind pro Bindung (ein durchgesickerter kann keinen anderen Verbraucher impersonieren), servicebezogen (jeder gültige Schlüssel erreicht jede Methode; teilen Sie Dienste, um separat zu sperren), werden nur durch Entfernen der Bindung oder Zerstören des Stacks und erneutes Bereitstellen rotiert und in bereitstellungeigenen COMPOSER_*-Variablen gespeichert, die Sie niemals von Hand bearbeiten.
  2. Idempotenz und Wiederholungen. Jeder generierte Client-Aufruf trägt einen Idempotency-Key; verworfene Aufrufe wiederholen sich mit Backoff, und serve() führt einen Aufruf pro Schlüssel aus und spielt die abgeschlossene Antwort für späte Wiederholungen erneut ab. Jede Methode ist daher sicher wiederholbar, und kein Vertrag deklariert etwas darüber (es gibt kein "ist das idempotent"-Flag; erfinden Sie keins). Ein Handler kann ein optionales drittes Argument (input, deps, ctx) nehmen und ctx.idempotencyKey (string | undefined) lesen, wenn es genau-einmal über den Speicher einer Instanz hinaus benötigt; die meisten tun dies nicht. Lokal und in Tests wird nichts bereitgestellt, daher gibt serve() jeden Aufruf durch: Liefern Sie niemals einen Schlüssel in Testeingaben.

Builds sind Ihre Sache

Sie bauen, das Framework setzt zusammen. Für einen einfachen Server-Prozess muss entry auf eine einzelne in sich geschlossene ESM-Datei zeigen: alles inline außer Runtime-Builtins (bun, bun:*, node:*). Die Bereitstellung kopiert diese eine Datei und liefert niemals node_modules aus, daher schlägt alles, was nicht inline ist, beim Booten fehl, nicht bei der Bereitstellung. Regeln, die beißen:

  1. Zwei Dienste in einem Paket bedeuten zwei separate Builds, einen pro Eintrag. Ein einzelner Multi-Entry-Build teilt gemeinsamen Code in einen Block, den keine der Ausgaben enthält.
  2. Ein Verzeichnis-Build verwendet dir + entry (dir relativ zum Service-Modul, entry eine Datei innerhalb von dir; ../ ist ein Fehler). Der Baum wird wörtlich kopiert, daher muss der Server Geschwister gegen import.meta.url auflösen, nicht gegen das Arbeitsverzeichnis. Der Baum darf keine Symlinks enthalten: Der Packer lehnt sie ab, benennt den Link, und die Zusammenstellung schlägt fehl.
  3. Next.js: next build mit output: 'standalone' ist der gesamte Build; nextjs({ module, appDir }) benennt die App-Wurzel. Jede Seite oder Aktion, die load() aufruft, benötigt export const dynamic = 'force-dynamic', da die Runtime-Umgebung zum Bauzeitpunkt nicht existiert und Next Runtime-Env für vorgerenderte Routen ignoriert.
  4. Vor deploy oder dev immer bauen. Keines von beiden baut für Sie.

Die Bereitstellungskonfiguration ist der composer-Abschnitt von prisma.config.ts und nichts anderes. Sie registriert Erweiterungen (prismaCloud(), nodeBuild(), nextjsBuild(), wenn die App einen Next.js-Dienst hat) und das Backend des Bereitstellungszustands (prismaState()):

// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';

export default definePrismaConfig({
  composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});

Die Befehle finden prisma.config.ts von dem Verzeichnis aus, in dem sie ausgeführt werden, und steigen bis zum Repository-Stamm auf; die nächste Datei, die composer deklariert, gewinnt, und ihr Abschnitt wird als Ganzes verwendet, nie Schlüssel für Schlüssel zusammengeführt. Nur extensions und state sind erlaubt; jeder andere Schlüssel ist ein Fehler. App-Code importiert die Datei nie.

Eine separate prisma-composer.config.ts wird nicht mehr gelesen, und das alte Setup wird abgelehnt, nie still ignoriert: CONFIG.SECTION_MISSING, wenn keine geladene prisma.config.ts einen composer-Abschnitt deklariert, CONFIG.FIELD_RETIRED, wenn der Abschnitt noch configPath hat, CONFIG.FILE_RETIRED, wenn ein prisma-composer.config.* neben der deklarierenden prisma.config.ts sitzt; alle drei unter dem CLI.CONFIG_SECTION_INVALID der CLI. Die Behebung für alle drei besteht darin, die extensions und state der alten Datei in den Abschnitt zu verschieben und die alte Datei zu löschen. @prisma/composer-cli/family exportiert ComposerSection nicht mehr; der Typ des Abschnitts ist PrismaAppConfig von @prisma/composer/config.

Datenbanken und Migrationen

Zwei Arten von Postgres-Abhängigkeit:

  1. rawPostgres(): Die Bindung ist { url } und die App besitzt ihren Client.
  2. postgres(...): Eine Prisma-ORM-typisierte Datenbank. Die Bindung ist { url, client } (ADR-0040): die rohe Verbindungs-URL plus den typisierten Client, den Composer aus Ihrem Datenvertrag konstruiert, lazy beim ersten Zugriff, sodass Abfragen über binding.client laufen und zur Kompilierzeit überprüft werden. Sowohl postgres als auch dataContract werden von @prisma/composer-prisma-cloud/orm importiert, nicht vom Paketstamm. Ein mit dataContract umschlossener Wert (von contract.prisma durch prisma contract emit ausgegeben) wird sowohl vom Abhängigkeitsende (deps: { db: postgres(catalogData) }) als auch vom Ressourcenende referenziert, das auch den Pfad von prisma.config.ts benennt, damit der Migrationsschritt der Bereitstellung den ausgegebenen contract.json neu laden und migrations/ finden kann.

Bereitstellungen sind Nur-Wiedergabe: Sie wenden die Migrationen an, die unter migrations/ committet wurden, und erstellen niemals selbst ein Schema. Jede Schemaänderung, einschließlich des ersten Schemas einer neuen Datenbank, folgt einer Schleife:

  1. Bearbeiten Sie contract.prisma.
  2. prisma contract emit regeneriert contract.json + contract.d.ts.
  3. prisma migration plan --name <slug> erstellt die Migration (bei einem leeren Graphen erstellt dies die Basislinie).
  4. Committen Sie migrations/ mit der Änderung und stellen Sie sie dann bereit. Eine neue Datenbank spielt den gesamten Pfad von leer ab.

Jeder Dienst, der die Datenbank verwendet, wird erst bereitgestellt, nachdem seine Migration abgeschlossen ist: Eine fehlgeschlagene Migration bedeutet, dass der neue Code nicht ausgeliefert wird. Der alte Code bedient das neue Schema, bis die neue Bereitstellung live ist, halten Sie daher jede Migration kompatibel mit dem Code, den sie ersetzt.

Wenn kein erstellter Pfad den Zielvertrag erreicht, verweigert die Bereitstellung (und dev gegen eine veraltete lokale Datenbank) mit MIGRATION_PATH_NO

… [für die Übersetzung gekürzt]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills