Přeskočit na obsah

Tato stránka byla automaticky přeložena z angličtiny, jediného jazyka, ve kterém se tento web píše. Číst originál.

HTTP API: web

Co tento repozitář vystavuje přes HTTP, určeno z producentů, kteří to vytvářejí, a ne z registru, který by někdo udržoval: trasy, na které odpovídá samotný spustitelný soubor, build dokumentace a každá vygenerovaná zpráva, která deklarovala vlastní mount. Stejné určení obsluhuje router, vykresluje domovskou stránku a skládá publikaci.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

web

Co tento repozitář vystavuje přes HTTP, určeno z producentů, kteří to vytvářejí, a ne z registru, který by někdo udržoval: trasy, na které odpovídá samotný spustitelný soubor, build dokumentace a každá vygenerovaná zpráva, která deklarovala vlastní mount. Stejné určení obsluhuje router, vykresluje domovskou stránku a skládá publikaci.

GET /api/v1/web/surfaces web.surfaces

Každý webový povrch, rozřešený

Webová topologie v pořadí priority tras, s připojením, kategorií, viditelností, druhem, producentem, artefaktem, runtime funkcí každého povrchu a původem každé hodnoty, která by čtenáře mohla překvapit; a které id se poskytují, publikují a nabízejí člověku. Odpovídá z vyřešení, ze kterého tento proces poskytuje, takže se nemůže rozejít s tím, co směruje router nebo co vypisuje domovská stránka.

  • query
  • behaviorally_verified
  • vyžaduje se měření výkonu
  • cache process (max_entries=2, ttl_seconds=5)
  • Nástroj MCP majordomus_web_surfaces
  • MCP zdroj {"name": "web", "uri": "majordomus://web"}

Žádné parametry.

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/web/surfaces"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

statustělovýznam
200 SurfaceReport Každý webový povrch, rozlišený: výsledek.
400 ErrorBody invalid_input: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404 ErrorBody not_found: Vstup pojmenovává něco, co repozitář nemá.
500 ErrorBody internal: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí ErrorBody Jakékoli jiné selhání, které transport hlásí: 405 method_not_allowed pro jinou metodu na této cestě, 400 invalid_input pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

Funkce

"mcp" | "cockpit" | "ui"
Schopnost běžícího procesu, kterou povrch potřebuje, aby mohl existovat.

Registr popisuje účinný proces, ne maximální: build nebo vyvolání, které neodpovídá na žádné MCP, nemá povrch MCP a úvodní stránka na něj nemůže odkázat. Uvedení závislosti jako dat je to, co to drží automatické.

  • mcpTento proces odpovídá MCP přes HTTP.
  • cockpitTento proces obsluhuje Cockpit.
  • uiTento proces servíruje UI: majordomus ui, primární povrch (ADR 0135).

Používá Surface

Připojit

string
Absolutní cesta připojení bez koncového lomítka.

Používá Surface

Původ

jedna z 5 variant
Odkud se vyřešená hodnota vzala.

Uchováno pro každé pole, jímž může být spotřebitel překvapen, aby web explain mohlo odpovědět na „proč je to připojeno tady?“, aniž by někdo četl kód objevování.

varianta Čteno z registru schopností: trasy, které spustitelný soubor už deklaruje jednou.
zdroj"registry"ano
varianta Čteno z vlastní deklarace producenta vedle jeho výstupu (surface.json).
pathstringanoSoubor deklarace, relativní k repozitáři.
zdroj"producer-declaration"ano
varianta Odvozeno z toho, že soubor nebo adresář leží tam, kde ho konvence očekává.
pathstringanoCo bylo nalezeno, relativně k repozitáři.
zdroj"filesystem"ano
variant Odvozeno z vlastní konfigurace generátoru webu.
pathstringanoKonfigurační soubor, relativně k repozitáři.
zdroj"site-config"ano
variant Zdokumentovaná výchozí hodnota modelu pro hodnotu, kterou nikdo neuvedl.
zdroj"default"ano

Používá Surface

Povrch

object
Jeden vyřešený povrch: vše, co spotřebitel potřebuje, s původem toho, čím by mohl být překvapen.
vlastnosttyppovinnépopis
id string ano Identita, jedinečná napříč topologií; používá ji selektor --only a --exclude.
název string ano Jeden řádek: co čtenář vidí ve výpisu.
kategorie SurfaceCategory → SurfaceCategory ano K čemu to slouží, což je to, jak to výpis seskupuje.
viditelnost SurfaceVisibility → SurfaceVisibility ano Zda se člověku zobrazuje.
druh SurfaceKind → SurfaceKind ano Jak odpovídá.
mount Mount → Mount ano Kde odpovídá.
producent string ano Co to vytvořilo: příkaz, modul, nebo generátor, který zapisuje adresář.
funkce Feature | null → Feature ne Schopnost runtime, kterou potřebuje; chybí, pokud ji proces má vždy.
artifact string | null ne Generovaný adresář, relativně k repozitáři, pro statický povrch.
index string | null ne Soubor poskytovaný pro samotný mount, pokud ho plocha má.
dostupnost SurfaceAvailability → SurfaceAvailability ano Kam jdou soubory povrchu a kdo za něj odpovídá.
built_from string | null ne Revize, ze které byl artefakt sestaven, když ji jeho producent zaznamenal: to dělá ze zastaralého sestavení zjištění místo překvapení.
provenance mapa Provenance → Provenance ano Odkud pochází každá zajímavá hodnota, podle názvu pole.

Používá SurfaceReport

SurfaceAvailability

"both" | "served-only" | "published-only"
Zda je povrch součástí statické publikace, servírován jen za běhu procesu, nebo obojí.
  • bothPoskytuje běžící program a publikuje se jako soubory.
  • served-onlyOdpovídá běžící spustitelný soubor a nikdy se nepublikuje: route, kterou proces vypočítá, nebo build vytvořený pro mount tohoto serveru, ne pro nasazení.
  • published-onlyPublikováno jako soubory; běžící spustitelný soubor je servíruje ze stejného adresáře.

Používá Surface

SurfaceCategory

"interface" | "documentation" | "api" | "protocol" | "report"
K čemu povrch slouží, což je způsob, jak se čtenáři ukazuje.

Kategorie je jediný kus záměru, který mount nemůže nést: /openapi.json a /swagger sedí vedle sebe a jsou dokumentem a prohlížečem k němu. Seskupování se odvozuje z tohoto pole a nikdy ze seznamu cest vedeného jinde.

  • interfaceNěco, co člověk otevře a prohlíží: domovská stránka, Cockpit.
  • documentationPróza a reference psané pro člověka: web, Swagger UI.
  • apiStrojově čitelné rozhraní registru schopností.
  • protocolDrátový protokol, kterým mluví jiný program.
  • reportGenerované důkazy běhu: testovací zpráva, zpráva měření výkonu.

Používá Surface

SurfaceFinding

object
Jedna věc špatně na topologii, řečená tak, aby ji člověk mohl opravit bez čtení tohoto souboru.
vlastnosttyppovinnépopis
závažnost SurfaceFindingSeverity → SurfaceFindingSeverity ano Jak moc na tom záleží.
pravidlo string ano Pravidlo, které ho vytvořilo, dost stabilní na to, aby se dalo vyhledat grepem.
povrch string ano Povrch, kterého se to týká.
zpráva string ano Co je špatně.
náprava string ano Co s tím dělat.

Používá SurfaceReport

SurfaceFindingSeverity

"warning" | "error"
Jak moc nález záleží.
  • warningStojí za přečtení; servírování je stále koherentní.
  • errorTopologie se v tomto stavu nesmí obsluhovat ani publikovat.

Používá SurfaceFinding

SurfaceKind

"static-directory" | "native-route" | "redirect"
Jak povrch odpovídá na požadavek.

Jen to, co tento repozitář obsluhuje: adresář generovaných souborů, cesta, na kterou spustitelný soubor odpovídá sám, a přesměrování. Nový druh je nové chování, nikdy nový název téhož chování s jinými daty.

  • static-directoryGenerovaný adresář, připojený pod svým prefixem a servírovaný z disku.
  • native-routeCesta, na kterou spustitelný soubor odpovídá sám, z vlastního registru nebo ze svých obslužných funkcí.
  • redirectCesta, která odpoví přesměrováním na jinou.

Používá Surface

SurfaceReport

object
Webové povrchy tohoto repozitáře tak, jak je vyřešil proces, který odpovídá.
vlastnosttyppovinnépopis
povrchy pole Surface → Surface ano Každý rozřešený povrch v pořadí přednosti rout: v pořadí, v němž je router konzultuje, takže odpovídá první, jehož mount cestu vlastní.
served array of string ano Id, za která proces odpovídá, ve stejném pořadí. Povrch publikovaný, ale neobsluhovaný, zde chybí.
publikováno array of string ano Id, která publikace drží, ve stejném pořadí.
veřejné array of string ano Id nabízená člověku, což je to, co vypisuje úvodní stránka.
zjištění pole SurfaceFinding → SurfaceFinding ano Co o topologii, jak teď stojí, říká validace. Prázdné je zdravá odpověď; zjištění zde je totéž, které hlásí majordomus web validate, s jeho nápravou.

Používá web.surfaces

SurfaceVisibility

"public" | "internal"
Komu se povrch nabízí.

Dvě hodnoty a nic víc: povrch je buď nabízen k objevení člověkem, nebo je součástí topologie, aniž by byl inzerován. Obojí je vždy ve strojově čitelné odpovědi — skrytí obsluhované trasy před introspekcí by ji skrylo jen před lidmi, kteří ji udržují.

  • publicUvedeno pro člověka: objeví se na domovské stránce.
  • internalServírováno a introspektovatelné, ne inzerováno: mluví s ním stroj, nebo na něj odkazuje jiný povrch.

Používá Surface

Prohledává názvy a popisy všech stránek, které tento web publikuje.