Přejít na obsah
Flexideo
Skip to main content

Flexideo Replications – vzdálené úložiště verzí replikací

Stav dokumentu: platný provozní a produkční kontrakt Remote Version Store.

Tento dokument závazně určuje strukturu vzdáleného úložiště replikací, význam URI v poli B‑1, pojmenování aplikací a instancí, oddělení verzovaných dat a provozních zámků i roli služby replications.flexideo.cloud.

Změna tohoto kontraktu vyžaduje kompatibilitní posouzení, migraci dat podle potřeby a ověřené nasazení; není přípustné ji vykládat jen jako návrh.

1. Účel​

Flexideo Replikátor při rozdílové replikaci pracuje s historií předchozích verzí a se stopou replikace. Remote Version Store poskytuje jejich sdílené vzdálené úložiště; lokální historie a cache zůstávají podporovaným provozním režimem.

Služba Flexideo Replications:

  • poskytuje sdílené vzdálené úložiště historie replikací,
  • bezpečně odděluje aplikace a jejich jednotlivé instance,
  • nevnucuje uživatelům jednu konkrétní technologii,
  • dovoluje použít vlastní podporovaný S3‑kompatibilní provider,
  • udržuje URI uložiště jako explicitní součást konfigurace replikace,
  • neukládá přístupové údaje do XDS ani do B‑1,
  • je použitelná lokálním Replikátorem i službou Replication Service.

Spravované úložiště Flexideo běží nad Cloudflare R2 v dedikovaném bucketu:

flexideo-replications

Provozní doména služby:

replications.flexideo.cloud

Tato doména představuje službu a její správu, nikoliv samotný S3 endpoint Cloudflare R2.

2. Základní princip

2.1 Uživatel si může zvolit vlastní vzdálené úložiště​

Flexideo Replications není povinným jediným úložištěm.

Uživatel nebo partner může zvolit:

  1. spravované úložiště Flexideo Replications, nebo
  2. vlastní vzdálené úložiště, pokud používá podporovaný protokol/provider.

Tím zůstává architektura otevřená a přenositelná.

Příklad spravovaného úložiště Flexideo:

s3://flexideo-replications/renomia-rdo/PROD/

Příklad vlastního S3 úložiště zákazníka nebo partnera:

s3://customer-replications/flexideo/renomia-rdo/PROD/

Produkčně podporovaným vzdáleným protokolem je s3://. Jiné schéma B‑1 Replikátor odmítne explicitní diagnostikou Unsupported remote version store provider; jejich případné zavedení je změnou tohoto kontraktu.

3. B‑1 jako lokální cesta nebo provider-aware URI

3.1 Význam pole B‑1​

Pole B‑1 představuje kořen vzdáleného Version Store konkrétní aplikace a instance.

B‑1 nemá obsahovat:

  • Access Key ID,
  • Secret Access Key,
  • heslo,
  • connection string se secretem,
  • interní token Flexideo Replications,
  • jiný citlivý autentizační údaj.

B‑1 obsahuje buď absolutní Windows cestu {$znakDisku}:\..., nebo provider URI. Disková cesta je kanonický tvar lokálního file store a nepřepisuje se na file://. URI určují:

  • protokol/provider,
  • bucket nebo ekvivalentní kontejner,
  • logickou cestu aplikace,
  • instanci.

Příklad:

s3://flexideo-replications/renomia-rdo/PROD/

3.2 Protokol je součást kontraktu​

Prefix URI je záměrně součástí B‑1:

s3://

Replikátor podle schématu URI určí, který provider má použít a které komunikační knihovny/adapter má aktivovat.

Princip:

B-1 URI
  ↓
rozpoznání schématu
  ↓
provider resolver
  ↓
aktivace odpovídajícího storage adapteru
  ↓
práce s Remote Version Store

Tím je oddělena logika replikace od konkrétního cloudového dodavatele.

Cloudflare R2 se z pohledu Replikátoru používá jako S3‑kompatibilní provider, tedy přes s3:// kontrakt a S3 API adapter.

4. Provozní režimy

Je-li B‑1 prázdné, Replikátor pracuje beze změny jen s lokální historií verzí. Absolutní disková cesta v B‑1 je podporovaný file-store režim. Po úspěšném uzavření verze například do C:\flexideo\web-backup\versions-store\ERP\CODE Replikátor vytvoří:

C:\flexideo\web-backup\versions-store\ERP\CODE\
  versions\
    updatelist.xml
    <verze>\
      trace.zip
      manifest.json

trace.zip obsahuje celou vyčištěnou složku uzavřené verze. Manifest obsahuje velikost a SHA-256 archivu. Existující artefakty stejné verze se nepřepisují. Po úspěšné publikaci se lokálně čistí jen starší uzavřené version folders, které už mají ve store neprázdný manifest a čitelný ZIP; vzdálená historie se automaticky nemaže.

Při porovnání dvou XDS verzí, při zobrazení detailu starší verze i před navazující replikací Replikátor chybějící historickou verzi materializuje z trace.zip: ověří SHA-256 podle manifestu, bezpečně ji rozbalí do dočasné složky a atomicky ji vloží do lokální cache. Pro s3:// používá S3 provider, při publikaci získá lease a registr aktualizuje podmíněným zápisem. Neprázdná B‑1 hodnota s nepodporovaným schématem skončí explicitní diagnostikou.​

5. Spravované úložiště Flexideo Replications

5.1 Bucket​

Dedikovaný bucket spravované služby:

flexideo-replications

Název je zvolen podle obsahu: bucket ukládá replikace a jejich verze, nikoliv samotný program Replikátor.

Bucket nemá sloužit jako obecné úložiště jiných Flexideo služeb.

5.2 Přístupová oprávnění​

Pro Replicator má být vytvořen samostatný přístup s oprávněním pouze pro tento bucket.

Pro Cloudflare R2 je cílové oprávnění:

Object Read & Write

Scope má být omezen pouze na:

flexideo-replications

Credential nemá mít širší práva k ostatním bucketům účtu.

5.3 S3 připojení Cloudflare R2​

Provider:

Cloudflare R2

S3 endpoint:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Region:

auto

Bucket:

flexideo-replications

Tyto technické údaje patří do provider konfigurace Replikátoru nebo služby, nikoliv do XDS definice aplikace.

6. Logická struktura úložiště

Každá aplikace má v bucketu vlastní jednoznačný kořen.

Pod aplikací následuje konkrétní instance.

Pod instancí jsou oddělena:

  • verzovaná data,
  • provozní koordinační objekty.

Výchozí struktura:

flexideo-replications/
│
├── <application-key>/
│   │
│   ├── DEV/
│   │   ├── versions/
│   │   │   ├── updatelist.xml
│   │   │   └── <version>/
│   │   │       ├── trace.zip
│   │   │       └── manifest.json
│   │   └── leases/
│   │       └── replication
│   │
│   ├── CODE/
│   ├── TEST/
│   ├── PRE/
│   ├── PROD/
│   ├── SPEC-1/
│   ├── SPEC-2/
│   └── OTHER-1/
│
└── <another-application-key>/

7. Application Key

7.1 Význam​

<application-key> je stabilní technický identifikátor aplikace používaný ve vzdáleném úložišti.

Není to volný zobrazovaný název.

Příklad:

renomia-rdo
headwork-crm
flexideo-docs

7.2 Požadavky​

Doporučený formát:

[a-z0-9-]

Pravidla:

  • lowercase,
  • bez mezer,
  • bez diakritiky,
  • pouze a-z, 0-9, -,
  • stabilní v čase,
  • jedinečný v rámci služby Flexideo Replications.

7.3 Stabilita identifikátoru​

Změna obchodního nebo zobrazovaného názvu aplikace nemá automaticky měnit application-key.

Například:

zobrazovaný název: Renomia RDO 2027
application-key:  renomia-rdo

Důvodem je zachování historie verzí a stabilních URI.

8. Instance aplikace

8.1 Standardní instance​

Výchozí typy instancí vycházejí z používaného modelu Flexideo:

CODE
DEV
TEST
PRE
PROD
SPEC
OTHER

Pro vzdálené úložiště se doporučuje rozlišovat standardní jedinečné instance a opakovatelné speciální instance.

Jedinečné standardní instance​

CODE
DEV
TEST
PRE
PROD

Tyto instance se nečíslují.

Správně:

PROD

Nedoporučeno:

PROD-1
PROD-2

8.2 SPEC a OTHER​

SPEC a OTHER mohou reprezentovat více paralelních instancí.

Proto se pro vzdálené úložiště doporučuje kanonický číslovaný tvar:

SPEC-1
SPEC-2
SPEC-3

OTHER-1
OTHER-2

Preferuje se, aby při použití vzdáleného úložiště nevznikala paralelně nečíslovaná a číslovaná forma stejného typu.

Tedy místo:

SPEC
SPEC-1

preferovat:

SPEC-1
SPEC-2

Stejné pravidlo platí pro OTHER.

9. Version Store instance

Kořen jedné instance:

s3://flexideo-replications/<application-key>/<instance>/

Příklad:

s3://flexideo-replications/renomia-rdo/PROD/

Pod tímto kořenem Replikátor používá pevně definované relativní cesty.

10. Složka versions

versions je persistentní Version Store instance.

Obsahuje:

  1. registr dostupných verzí,
  2. jednotlivé uložené verze,
  3. metadata potřebná k jejich interpretaci.
versions/
├── updatelist.xml
├── <version-1>/
│   ├── trace.zip
│   └── manifest.json
└── <version-2>/
    ├── trace.zip
    └── manifest.json

11. versions/updatelist.xml

11.1 Účel​

updatelist.xml je registr verzí dostupných pro konkrétní kombinaci:

application-key + instance

Například:

renomia-rdo + PROD

má vlastní registr oddělený od:

renomia-rdo + TEST

11.2 Umístění​

<application-key>/<instance>/versions/updatelist.xml

Umístění uvnitř versions je záměrné: registr patří k množině verzí, které eviduje.

11.3 Souběžně bezpečný zápis​

Registr je chráněn před přepsáním při souběžných operacích. S3 provider používá optimistic concurrency pomocí:

If-Match
If-None-Match

Princip:

READ updatelist.xml + ETag
       ↓
změna registru
       ↓
PUT s If-Match: <původní ETag>
       ↓
OK → registr bezpečně aktualizován
412 / konflikt → znovu načíst a rozhodnout

Struktura v následující části je závazným schématem registru pro Remote Version Store. Sdílený registr nesmí obsahovat atribut location.

11.4 Obsah registru verzí​

Sdílený registr je XML soubor versions/updatelist.xml. Nesmí se zaměňovat s lokální cache Replikátoru updates-list.mxl, která zůstává beze změny. Registr je funkční vstup pro načtení seznamu verzí i uložení jejich nastavení, nikoli pouhý export.

<updates-list>
  <versions view-only-last="false" cloned="" cloned-xds="">
    <version ...>
      <type>...</type>
    </version>
  </versions>
</updates-list>

Každý záznam version eviduje alespoň části čísla major, minor a revision, čitelný kód code, řaditelný code-no, popis caption, čas create-time, stav status, kanonický název složky subfolder, autora creator a příznak server-change. Podřízené prvky type určují dokumentové typy změněné ve verzi; u starší historie mohou být řízeně prořezány, aby registr nerostl neomezeně.

code-no může u historických záznamů chybět. location je naopak historický atribut lokálního registru: obsahuje absolutní cestu ke složce verze, a proto se nesmí bez úpravy kopírovat do sdíleného či vzdáleného registru. Pro přenositelnou identitu se používá subfolder nebo jiný explicitně definovaný relativní identifikátor.

Stav status určuje použitelnost verze: 0 je nově založená verze, 1 dokončené XDS, 2 dokončené DAD, 3 dokončená distribuční/cloud fáze, 4 vytvořené stránky a 5 dokončená instalace – uzavřená použitelná verze. Při výběru předchozí verze pro navazující operaci se musí pracovat jen se záznamem, jehož stav a dostupné artefakty odpovídají uzavřené verzi.

12. Jednotlivá verze

Každá uložená verze má samostatný adresář/prefix:

versions/<version>/

Příklad:

versions/2026.08.16.1730/

Formát <version> je kanonický časový identifikátor YYYY.MM.DD.HHMM, například 2026.08.16.1730. Musí být:

  • jednoznačný v rámci instance,
  • stabilní,
  • řaditelný nebo jednoznačně mapovatelný na pořadí replikací,
  • bezpečný jako objektový klíč,
  • nezávislý na zobrazovaném textu.

Při importu historické verze se její původní identifikátor mapuje na tento tvar a původní zobrazený kód zůstává v code.

13. trace.zip

Umístění:

versions/<version>/trace.zip

trace.zip představuje uloženou replikační stopu potřebnou pro navazující rozdílovou replikaci.

Provozní postup:

předchozí verze
   ↓
stažení trace.zip
   ↓
materializace do lokální pracovní/cache struktury
   ↓
rozdílová replikace
   ↓
nová trace
   ↓
upload nové verze

Přesný interní obsah ZIPu zůstává kontraktem Replikátoru a nemá být závislý na Cloudflare R2.

14. manifest.json

Umístění:

versions/<version>/manifest.json

Manifest je metadata konkrétní uložené verze.

Jeho cílem je umožnit bezpečně zjistit například:

  • identitu aplikace,
  • identitu instance,
  • identitu verze,
  • čas vytvoření,
  • kompatibilní verzi Replikátoru/platformy,
  • typ replikace,
  • checksum/hash artefaktů,
  • velikost artefaktů,
  • vazbu na předchozí verzi,
  • případně stav dokončení.

Manifest je UTF-8 JSON objekt s povinnými poli applicationKey, instance, version, createdAt, replicatorVersion, replicationType, previousVersion, traceSha256 a traceSize. Hodnoty applicationKey, instance a version musí odpovídat prefixu objektu; traceSha256 je malými hexadecimálními znaky SHA-256 a traceSize je nezáporné celé číslo v bajtech.

Manifest nesmí být používán jako úložiště tajných údajů.

15. leases/replication

15.1 Oddělení od verzí​

Lease je provozní koordinační objekt, nikoliv historická verze.

Proto je oddělen od versions:

<application-key>/<instance>/leases/replication

15.2 Účel​

Lease chrání operace, které nesmějí běžet souběžně nad stejnou instancí.

Například:

renomia-rdo/PROD

může mít aktivní pouze jednu operaci, která mění registr verzí.

15.3 Lease není jediná ochrana konzistence​

Lease nenahrazuje optimistic concurrency nad updatelist.xml.

Používaný model:

lease
  +
ETag / conditional write

Lease omezuje nežádoucí souběh na aplikační úrovni.

Conditional write chrání samotný objekt proti race condition na storage úrovni.

16. Doporučené URI v B‑1

Flexideo Replications​

s3://flexideo-replications/renomia-rdo/PROD/

Speciální instance​

s3://flexideo-replications/renomia-rdo/SPEC-1/

Jiná aplikace​

s3://flexideo-replications/headwork-crm/TEST/

Vlastní S3 úložiště partnera​

s3://partner-flexideo-replications/client-app/PROD/

Samotné URI neurčuje credentials. Provider konfigurace musí credentials získat samostatně.

17. Credentials a secrets

17.1 Co nesmí být v B‑1​

Zakázaný příklad:

s3://ACCESS_KEY:SECRET_KEY@flexideo-replications/renomia-rdo/PROD/

Stejně tak se secret nesmí zapisovat do XML aplikační konfigurace.

17.2 Správný princip​

B-1
    = kde je store

provider configuration
    = jak se k němu připojit

secret store / environment / secure host configuration
    = credential

Například:

B-1:
s3://flexideo-replications/renomia-rdo/PROD/

Provider:
Cloudflare R2

Endpoint:
https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Region:
auto

Credential:
uložen mimo XDS a mimo B-1

18. Provider resolver

Replikátor odděluje společný Version Store kontrakt od providerů.

Příklad rozhraní:

IRemoteVersionStore
│
├── GetRegistry()
├── PutRegistryConditional()
├── GetVersionArtifact()
├── PutVersionArtifact()
├── GetManifest()
├── PutManifest()
├── AcquireLease()
└── ReleaseLease()

Provider implementace:

IRemoteVersionStore
│
├── S3RemoteVersionStore
│   ├── Cloudflare R2
│   ├── AWS S3
│   ├── MinIO
│   └── jiný S3-compatible provider
│
└── nepodporovaná schémata (explicitní diagnostika)

Cloudflare R2 tedy nemá prostupovat do replikační doménové logiky.

Je pouze konkrétní implementací storage adapteru.

19. Konfigurace S3 provideru

Samotné s3:// URI nestačí k rozlišení konkrétního S3 endpointu.

Provider konfigurace musí umět dodat minimálně:

Endpoint
Region
Access Key ID
Secret Access Key

Pro Flexideo Replications:

Endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
Region: auto
Bucket: flexideo-replications

Bucket lze přečíst také přímo z URI.

Credentials se mapují na endpoint a bucket z bezpečné konfigurace běhu Replikátoru; nesmějí být vloženy do aplikační definice, B‑1 ani diagnostiky.

20. Role replications.flexideo.cloud

replications.flexideo.cloud je provozní doména pro správu služby Flexideo Replications.

Nemá nahrazovat S3 endpoint R2.

Poskytuje:

  • přehled aplikací,
  • správu application-key,
  • správu instancí,
  • přehled uložených verzí,
  • audit replikací,
  • stav poslední replikace,
  • správu oprávnění,
  • generování nebo správu přístupů,
  • diagnostiku storage,
  • API služby.

20.1 Co doména nemá být​

Nemá to být obecná marketingová stránka.

Produktové vysvětlení patří do informační vrstvy .com.

replications.flexideo.cloud odpovídá na otázku:

Kde se služba používá a spravuje?

21. Spravované versus vlastní úložiště

21.1 Spravované Flexideo Replications​

Výhody:

  • jednotná konfigurace,
  • není třeba provozovat vlastní object storage,
  • standardizovaný provider,
  • centrální správa oprávnění,
  • jednodušší podpora,
  • základ pro budoucí Replication Service.

Příklad B‑1:

s3://flexideo-replications/<application-key>/<instance>/

21.2 Vlastní vzdálené úložiště​

Partner nebo zákazník může používat vlastní úložiště, pokud splní podporovaný provider contract.

Příklad:

s3://my-company-version-store/flexideo-app/PROD/

Vlastník vlastního úložiště odpovídá za:

  • dostupnost,
  • credentials,
  • retention,
  • oprávnění,
  • storage limity,
  • kompatibilitu S3 API,
  • podporu podmíněných zápisů potřebných implementací,
  • případné lifecycle rules.

Replikátor má validovat technické předpoklady a při nekompatibilitě vrátit explicitní diagnostiku.

22. Vytváření nové aplikace ve Flexideo Replications

Navrhovaný postup:

  1. určit stabilní application-key,
  2. ověřit jeho jedinečnost,
  3. určit první instanci,
  4. vytvořit logický root instance,
  5. nastavit B‑1,
  6. ověřit dostupnost provideru,
  7. ověřit read/write oprávnění,
  8. inicializovat versions/updatelist.xml, pokud to kontrakt vyžaduje,
  9. provést první replikaci,
  10. uložit trace a manifest,
  11. bezpečně aktualizovat registr.

Objektové úložiště nepotřebuje reálné adresáře. „Složky“ v tomto dokumentu reprezentují prefixy objektových klíčů.

23. Vytváření nové instance

Standardní instance:

CODE
DEV
TEST
PRE
PROD

Speciální instance:

SPEC-1
SPEC-2
OTHER-1

Příklad:

renomia-rdo/
├── DEV/
├── TEST/
├── PRE/
├── PROD/
└── SPEC-1/

Každá instance má vlastní historii.

Historie se mezi instancemi nesdílí automaticky.

24. Nezaměňovat Version Store a výsledný build

Remote Version Store je primárně infrastruktura pro historii a návaznost replikací.

Není automaticky totožný s distribučním úložištěm výsledné aplikace.

Rozlišovat:

Remote Version Store
    trace, manifest, registry

oproti:

Build / release artifact storage
    instalační nebo distribuční výsledek

Pokud se později rozhodne ukládat výsledné artefakty do stejného bucketu, musí vzniknout samostatně definovaný prefix a kontrakt. Nemá se nekontrolovaně míchat do versions/.

25. Retence a mazání

Historie se automaticky nemaže. Retenci nebo odstranění verze smí provést pouze řízená provozní operace s auditním záznamem.

Pravidla:

  • aktivní verze nesmí být odstraněna, pokud na ni navazuje rozdílová replikace,
  • updatelist.xml musí vždy odpovídat fyzicky dostupným verzím,
  • smazání verze musí být řízená operace,
  • lifecycle pravidla object storage nesmějí svévolně mazat objekty bez znalosti aplikačních vazeb.

Lifecycle pravidla object storage nesmějí automaticky mazat trace.zip, manifest.json ani registr.

26. Immutability uložených verzí

Po úspěšném dokončení verze se má její obsah považovat za neměnný.

Preferovaný princip:

versions/<version>/trace.zip      immutable
versions/<version>/manifest.json  immutable po finalizaci

Měnitelným objektem je zejména registr:

versions/updatelist.xml

Tím se výrazně zjednodušuje:

  • audit,
  • cache,
  • retry,
  • kontrola checksumů,
  • diagnostika.

27. Atomická publikace nové verze

Doporučené pořadí:

1. získat lease, pokud je používán
2. načíst registry + ETag
3. provést replikaci
4. vytvořit trace.zip
5. vytvořit manifest.json
6. uploadnout artefakty nové verze
7. ověřit upload
8. conditional PUT updatelist.xml
9. označit operaci jako úspěšnou
10. uvolnit lease

Klíčový princip:

Nová verze se považuje za publikovanou až ve chvíli, kdy je bezpečně uvedena v registru.

Pokud upload artefaktů proběhne, ale aktualizace registru selže, vzniká orphan kandidát, který nesmí být automaticky považován za platnou verzi.

28. Recovery a orphan objekty

Implementace má počítat s přerušením mezi:

upload artefaktů

a:

aktualizace updatelist.xml

Proto musí být možné:

  • identifikovat objekt verze, který není v registru,
  • bezpečně rozhodnout, zda jej dokončit nebo odstranit,
  • neopravovat stav pouze heuristikou názvu objektu.

manifest.json může být důležitou součástí recovery procesu.

29. Lokální cache

Remote Version Store nemá znamenat, že Replikátor musí všechny operace provádět přímo nad vzdálenými objekty.

Doporučená architektura:

Remote Version Store
      ↓
materializace požadované verze
      ↓
Local Version Cache
      ↓
Replikátor

Výhody:

  • minimální zásah do existující replikační logiky,
  • opakované použití již stažené verze,
  • odolnost proti krátkodobým výpadkům,
  • jednodušší diagnostika.

Cache je ale pouze lokální optimalizace.

Zdroj pravdy je vzdálený Version Store, pokud je B‑1 aktivní.

30. Chování bez B‑1

Zpětná kompatibilita je zásadní.

Pokud B‑1 není definované:

B-1 = empty

Replikátor musí pokračovat v existujícím lokálním režimu.

Remote Version Store nesmí být povinný pro stávající projekty.

31. Chování při definovaném B‑1

Cílově:

B-1 != empty

znamená:

  1. rozpoznat provider URI,
  2. načíst provider konfiguraci,
  3. ověřit dostupnost vzdáleného store,
  4. materializovat potřebnou předchozí verzi,
  5. provést replikaci,
  6. publikovat novou verzi,
  7. aktualizovat registry.

Pokud provider není podporován, má Replikátor skončit explicitní diagnostikou typu:

Unsupported remote version store provider

nikoliv tiše pokračovat jiným způsobem.

32. Bezpečnostní zásady

  1. Credentials nejsou součástí XDS.
  2. Credentials nejsou součástí B‑1.
  3. Token pro Flexideo R2 je omezen pouze na bucket flexideo-replications.
  4. Oprávnění má být minimálně nutné pro konkrétní implementaci.
  5. Jednotlivé aplikace mohou v budoucnu dostat jemnější oddělení oprávnění.
  6. Přenos probíhá přes zabezpečené S3 API endpointy.
  7. Logy nesmějí vypisovat Secret Access Key.
  8. Diagnostika může uvádět endpoint, bucket a prefix, ale ne secrets.

33. Oddělení tenantů

Bucket může dlouhodobě obsahovat více aplikací:

flexideo-replications/
├── app-a/
├── app-b/
├── app-c/
└── ...

Samotná cesta ale není bezpečnostní hranice.

Při poskytování replications.flexideo.cloud více partnerům nebo zákazníkům je autorizace řešena službou nebo jemně omezenými credentials.

Není přijatelné spoléhat na to, že uživatel „zná pouze svůj prefix“.

34. Vazba na Replication Service

Remote Version Store je přirozeným podkladem pro vzdálenou Replication Service.

Provozní tok:

Client / XDS Authoring / Agent
        ↓
Replication Service
        ↓
Replikátor
        ↓
Remote Version Store
        ↓
nová verze + registry

Tím může stejnou historii používat:

  • lokální Replikátor,
  • cloudový replikační worker,
  • validační nástroje,
  • agentní workflow.

Version Store není svázán pouze s jedním způsobem spuštění replikace.

35. Vazba na agentní workflow

AI nebo agent nesmí přímo manipulovat s jednotlivými R2 objekty bez znalosti kontraktu.

Preferovaný model:

Agent
  ↓ záměr
Replication / XDS Authoring service
  ↓ validované operace
Version Store adapter
  ↓
R2 / S3

Architektura, schémata a validace zůstávají zdrojem kontroly.

Agent může navrhovat operaci, ale nemá obcházet provider contract a konzistenční pravidla.

36. Diagnostika

Remote Version Store musí poskytovat srozumitelné diagnostiky minimálně pro:

  • neplatné B‑1 URI,
  • nepodporovaný protokol,
  • nedostupný endpoint,
  • neexistující bucket,
  • nedostatečná oprávnění,
  • chybějící updatelist.xml,
  • neexistující referencovanou verzi,
  • poškozený manifest.json,
  • checksum mismatch,
  • konflikt conditional write,
  • neúspěšné získání lease,
  • timeout,
  • neúspěšný upload/download.

Diagnostika má rozlišit:

CONFIGURATION ERROR
PROVIDER ERROR
CONSISTENCY ERROR
REPLICATION ERROR

aby bylo zřejmé, zda je problém v XDS/replikaci nebo v Remote Version Store.

37. Doporučené validační kontroly B‑1

Před spuštěním replikace lze validovat:

scheme          = podporovaný
bucket          = neprázdný
application-key = validní
instance        = validní
URI             = normalizované
credentials     = dostupné z bezpečné konfigurace
endpoint        = dostupný
read            = povolen
write           = povolen

U Flexideo Replications navíc:

bucket == flexideo-replications

může být očekávaný výchozí stav, ale Replikátor obecně nesmí hardcodovat, že s3:// smí používat pouze tento bucket.

38. Normalizace cest

Doporučuje se kanonický tvar B‑1 zakončený /:

s3://flexideo-replications/renomia-rdo/PROD/

Interně má resolver cestu normalizovat, aby ekvivalentní zápisy nevytvářely různé logické stores.

Například:

.../PROD
.../PROD/

nemají být interpretovány jako dvě různé instance.

39. Objektové klíče a názvy

Zakázat nebo normalizovat:

  • ..,
  • prázdné segmenty,
  • backslash \,
  • řídicí znaky,
  • náhodné URL encoding varianty stejného jména.

Provider adapter má pracovat s kanonickými objektovými klíči.

40. Příklady kompletních objektových klíčů

Pro:

application-key = renomia-rdo
instance        = PROD
version         = 2026.08.16.1730

vzniknou například:

renomia-rdo/PROD/versions/updatelist.xml
renomia-rdo/PROD/versions/2026.08.16.1730/trace.zip
renomia-rdo/PROD/versions/2026.08.16.1730/manifest.json
renomia-rdo/PROD/leases/replication

B‑1:

s3://flexideo-replications/renomia-rdo/PROD/

41. Provozní závazky a přijetí

Remote Version Store je přijat do produkčního provozu s těmito závazky:

  • prázdné B‑1 zachovává lokální režim; s3:// aktivuje S3 provider,
  • Cloudflare R2 funguje výhradně jako S3-compatible provider a neprostupuje do doménové logiky Replikátoru,
  • credentials nejsou v B‑1 ani XML a přístup je omezen na nezbytný bucket a prefix,
  • aplikace a instance používají kanonické identifikátory, registr je pod versions/ a každá publikovaná verze obsahuje trace.zip a platný manifest.json,
  • lease je oddělen od historie a podmíněný zápis registru chrání publikaci před race condition,
  • chybějící, poškozená nebo nedostupná historie vede k explicitní diagnostice; Replikátor ji nenahrazuje jiným zdrojem bez vědomí obsluhy,
  • uživatel může místo Flexideo Replications použít vlastní podporovaný S3 store.

Před každým produkčním nasazením se ověřuje parser B‑1, přístup k provideru, čtení a zápis do určeného prefixu, podmíněný zápis registru, získání a uvolnění lease, kontrola SHA-256, materializace cache a bezpečné zotavení z nedokončené publikace. Výsledek je součástí záznamu nasazení.

44. Výsledný architektonický princip

B-1
s3://flexideo-replications/renomia-rdo/PROD/
        │
        ▼
Provider resolver
        │
        ▼
S3 Version Store adapter
        │
        ▼
Cloudflare R2
flexideo-replications
        │
        └── renomia-rdo/
            └── PROD/
                ├── versions/
                │   ├── updatelist.xml
                │   └── <version>/
                │       ├── trace.zip
                │       └── manifest.json
                └── leases/
                    └── replication

Zásadní pravidlo:

B‑1 definuje, kde se Version Store nachází a jakým protokolem se k němu přistupuje. Provider adapter řeší komunikaci. Credentials zůstávají mimo aplikační definici. Struktura Version Store zůstává stejná bez ohledu na konkrétní S3‑kompatibilní službu.

A pro spravovanou službu Flexideo: