APIS Modules

APIS moduly definují, čemu systém rozumí, co umí produkovat a co umí vykonávat.

V praxi jsou moduly stavební bloky, které popisují projektovou automatizaci. Říká se v nich APIS, jaké artefakty existují, které joby je umí transformovat a které runtime komponenty jsou dostupné pro výkon flow.

Proč moduly existují

Reálný projekt bývá zřídka jedním plochým repozitářem s jediným výstupem. Ve většině případů jde o graf repozitářů, artefaktů a navazujících kroků.

APIS používá moduly k tomu, aby tento graf modeloval strukturovaně:

• Item moduly popisují artefakty, jako jsou archivy, dokumentace, obrázky nebo 3D modely.
• Job moduly popisují transformace mezi artefakty.
• Environment moduly popisují, kde se výkon odehrává.
• Executor moduly popisují, jak se práce skutečně vykoná.

Díky tomuto návrhu umí APIS generovat flow vědomé o závislostech místo spoléhání na hardcoded skripty pro každý projekt.

Jak moduly zapadají do generování flow

Kódová základna převádí moduly do dvou hlavních flow prvků:

• ApisItemData reprezentuje artefakt v grafu závislostí.
• ApisJobData reprezentuje job, který jednu sadu artefaktů spotřebovává a jinou produkuje.

Když APIS moduly načte, vytvoří graf vstupů a výstupů. Ten se pak dá použít pro generování projektového flow, vizualizaci závislostí a spouštění automatizace lokálně i v CI/CD.

Typy modulů

Item moduly

Item moduly definují pojmenované typy artefaktů. Aktuální kódová základna už obsahuje příklady jako:

• archivy
• výstupy pro SCP publikaci
• výstupy pro HTTP post
• spustitelne soubory
• 3D modely
• dokumentace
• PCB schéma, BOM, CPL a gerber výstupy
• obrázky

Každý item zároveň patří do širší kategorie, např. FILE, DIRECTORY, DOCUMENT, IMAGE, TABLE nebo DATA.

Job moduly

Job moduly definují samotné transformace v grafu.

Job modul deklaruje:

• jméno modulu
• runtime image
• vstupní typy artefaktů
• výstupní typy artefaktů
• volitelnou konfigurační dataclass
• stage v exekuční pipeline

Stage jsou v aktuální kódové základně řazeny takto:

1. INITIALING
2. BUILDING
3. TESTING
4. PACKAGING
5. PUBLISHING

Tento stage model dává APIS předvídatelnou exekuční strukturu a přitom nechává konkrétní job logiku modulární.

Environment moduly

Environment moduly reprezentují kontext vykonání a poskytují file tree i execution hooky.

Jejich účelem je popsat, kde APIS běží a jaká projektová data tam má k dispozici.

Executor moduly

Executor moduly reprezentují komponentu, která výkon skutečně provádí.

Díky tomu zůstává definice jobů oddělena od mechanismu, který je fyzicky spouští.

Konfigurační model

Job moduly mohou mít připojené konfigurační objekty odvozené od ApisJobConf.

Tyto konfigurace jsou složené z typovaných parametrů, např.:

• řetězce
• hesla
• IP adresy
• URL adresy

To umožňuje nastavovat moduly bez toho, aby se každý job měnil v jednorázový skript.

Vlastní moduly

APIS je navržen tak, aby načítal moduly z balíčků i z modulových adresářů v projektové konfiguraci.

To znamená, že projekt může rozšířit built-in chování o vlastní moduly specifické pro firemní infrastrukturu, artefakty i pravidla distribuce.

Built-in moduly, které jsou aktuálně v repozitáři, jsou popsané na další stránce.