Skip to main content

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

Stav dokumentu: výchozí návrh / architektonický kontrakt určený k revizi při implementaci Remote Version Store a služby Flexideo Replications.

Tento dokument definuje doporučenou 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ů a cílovou roli služby provozované pravděpodobně pod replications.flexideo.cloud.

Dokument záměrně odděluje současný stav, cílový návrh a budoucí možnosti. Co není výslovně označeno jako implementované, je návrh určený k realizaci a validaci.

1. Účel​

Flexideo Replikátor potřebuje při rozdílové replikaci pracovat s historií předchozích verzí a se stopou replikace. Dosud je tento stav primárně lokální. Cílem Remote Version Store je umožnit, aby byla historie verzí dostupná také ve vzdáleném úložišti.

Výchozí cloudová služba Flexideo má být postavena tak, aby:

  • poskytovala sdílené vzdálené úložiště historie replikací,
  • umožnila bezpečně oddělit aplikace a jejich jednotlivé instance,
  • nevnucovala uživatelům jednu konkrétní technologii,
  • dovolila použít vlastní S3‑kompatibilní nebo v budoucnu jiný podporovaný provider,
  • udržela URI uložiště jako explicitní součást konfigurace replikace,
  • neukládala přístupové údaje do XDS ani do B‑1,
  • byla použitelná lokálním Replikátorem i budoucí vzdálenou Replication Service.

Výchozí spravované úložiště Flexideo je navrženo nad Cloudflare R2 v dedikovaném bucketu:

flexideo-replications

Předpokládaná 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/

V budoucnu může být podporován jiný protokol, například:

azblob://...
https://...

Konkrétní seznam podporovaných providerů musí být vždy definován implementací Replikátoru. Tento dokument neurčuje, že jiné protokoly než s3:// jsou již implementované.

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. Současný stav implementace

Implementován je první publikační provider pro B‑1 s absolutní diskovou cestou. Je-li B‑1 prázdné, Replikátor pracuje beze změny jen s lokální historií verzí.

Je-li v B‑1 například C:\flexideo\web-backup\versions-store\ERP\CODE, po úspěšném uzavření verze 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í i při zobrazení detailu zvolené starší verze Replikátor umí chybějící historickou verzi obnovit 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. Obecné načítání historie před replikací, S3 provider, lease ani souběžná ochrana registru zatím implementovány nejsou. Neprázdná B‑1 hodnota, která není absolutní disková cesta, skončí při publikaci explicitní diagnostikou.​

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

5.1 Bucket​

Doporučený dedikovaný bucket:

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​

Cílová implementace musí chránit registr před přepsáním při souběžných operacích.

Pro S3‑kompatibilní provider se má využít optimistic concurrency, pokud provider podporuje podmíněné zápisy například přes:

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

Přesné schéma updatelist.xml je samostatný kontrakt a musí být definováno před finální implementací.

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> není tímto dokumentem definitivně určen. 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.

Finální formát musí být sladěn se současným verzováním Replikátoru.

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.

Cílový princip:

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í.

Přesný JSON schema není tímto dokumentem stanoveno a musí vzniknout jako samostatný explicitní kontrakt.

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 může sloužit k ochraně operací, 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.

Doporučený 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

Cílová implementace Replikátoru by měla oddělit 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
│
└── budoucí jiné providery

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.

Konkrétní způsob mapování credentials na bucket/endpoint musí být definován tak, aby nebylo nutné vkládat secrets do aplikační definice.

20. Role replications.flexideo.cloud

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

Nemá nahrazovat S3 endpoint R2.

Cílově může poskytovat například:

  • 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,
  • případně 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í

Retenční politika není tímto dokumentem definitivně stanovena.

Obecný princip:

  • 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.

Proto se nedoporučuje zavést automatické časové mazání trace.zip bez explicitního Version Store retention kontraktu.

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. Multi-tenant budoucnost služby

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

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

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

Pokud bude replications.flexideo.cloud poskytován více partnerům nebo zákazníkům, musí být autorizace řešena nad službou nebo jemněji omezenými credentials.

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

34. Budoucí vazba na Replication Service

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

Cílový 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,
  • budoucí agentní workflow.

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

35. Budoucí 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. Co je potřeba před implementací ještě uzavřít

Tento návrh záměrně nechává několik detailů otevřených.

Nutné kontrakty​

  1. definitivní formát <version>,
  2. schéma updatelist.xml,
  3. schema manifest.json,
  4. lease formát a timeout semantics,
  5. pravidla retry,
  6. recovery orphan verzí,
  7. lokální cache layout,
  8. provider configuration a secret resolution,
  9. migrace existující lokální historie do Remote Version Store,
  10. pravidla retention a mazání.

Tyto body nemají být domýšleny implicitně v kódu. Mají mít explicitní definici a testy.

42. Implementační etapy

Etapa A – S3 abstraction​

  • provider resolver podle URI scheme,
  • s3:// parser,
  • provider-neutral Version Store interface,
  • secure credential resolution.

Etapa B – Cloudflare R2 provider​

  • endpoint konfigurace,
  • region auto,
  • read/write objektů,
  • ETag,
  • conditional writes,
  • základní diagnostika.

Etapa C – Version Store contract​

  • versions/updatelist.xml,
  • trace.zip,
  • manifest.json,
  • publikace verze,
  • download předchozí verze.

Etapa D – concurrency​

  • lease,
  • If-Match / If-None-Match,
  • retry strategie,
  • conflict diagnostics.

Etapa E – local cache​

  • materializace trace,
  • cache key,
  • invalidace,
  • opětovné použití.

Etapa F – Flexideo Replications service​

  • replications.flexideo.cloud,
  • registr aplikací,
  • správa instancí,
  • audit,
  • autorizace,
  • případné API.

43. Akceptační kritéria základního Remote Version Store

Implementace je připravena k praktickému použití, pokud:

  • nevyplněné B‑1 zachovává původní lokální režim,
  • s3:// aktivuje S3 provider,
  • Cloudflare R2 funguje bez cloudflare-specific logiky v doméně Replikátoru,
  • credentials nejsou v B‑1 ani XML,
  • aplikace mají stabilní jednoznačné application-key,
  • standardní instance mají kanonické názvy,
  • SPEC a OTHER lze číslovat,
  • registry je uvnitř versions,
  • každá verze má trace.zip a manifest.json,
  • lease je oddělen od historie,
  • publikace registru je chráněna proti race condition,
  • poškozená nebo nedostupná vzdálená historie vede k explicitní diagnostice,
  • uživatel může místo Flexideo Replications zvolit vlastní podporovaný store.

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: