# Automatische resource-updates

De FiveM bridge bevat vanaf versie 0.8.0 de capability
`resource-updater-v1`. Daarmee kan het control-plane een geïnstalleerde
marketplaceresource handmatig of automatisch bijwerken zonder generieke shell-
of code-execution beschikbaar te maken.

## Vertrouwensgrenzen

Een update wordt alleen geaccepteerd wanneer:

1. de server een actief entitlement voor het product heeft;
2. de release gepubliceerd, compatibel en door object storage als geverifieerd
   gemarkeerd is;
3. de download-URL exact dezelfde origin heeft als `platform_api_url`;
4. het pad exact een Game Cloud marketplace-downloadpad is, met een geldige
   verval- en signatureparameter;
5. niet-lokale downloads HTTPS gebruiken;
6. het canonical manifest overeenkomt met het opdrachtmanifest;
7. manifest-SHA-256, Ed25519-publisherhandtekening, bestandsgrootte en
   artifact-SHA-256 allemaal kloppen.

Redirects worden niet gevolgd. Credentials, fragments, afwijkende hosts en
niet-allowlisted downloadpaden worden geweigerd. Downloadtokens zijn kort
geldig en eenmalig bruikbaar. De bridge kan zichzelf niet vanuit zijn eigen
runtime vervangen; een bridge-upgrade blijft een afzonderlijke beheerrelease.

## Installatieketen

De updater doorloopt en auditeert deze fasen:

`QUEUED → DOWNLOADING → VERIFYING → BACKING_UP → STAGING → SWITCHING →
RESTARTING → HEALTHCHECK → SUCCEEDED`

- De bestaande resourcedirectory wordt eerst volledig gekopieerd naar
  `.platform-backups/<resource>/<update-id>`. Symbolische links en onbekende
  bestandstypen worden geweigerd.
- ZIP-inhoud wordt uitsluitend in
  `.platform-staging/<update-id>` uitgepakt. Absolute paden, drivepaden,
  `..`-traversal, nulbytes en entries buiten staging zijn geblokkeerd.
- Een release bevat maximaal 1.000 entries en 250 MB uitgepakte data en moet
  `fxmanifest.lua` of `__resource.lua` in de root hebben.
- Na het stoppen van de resource wordt de huidige directory met een rename naar
  een swapdirectory verplaatst en staging met een tweede rename geactiveerd.
  Beide liggen op hetzelfde filesystem, zodat iedere directorywissel atomisch is.
- Na de restart moet de resource binnen 30 seconden `started` zijn en moet de
  `version`-metadata overeenkomen met de marketplaceversie.

## Rollback en crashherstel

Bij een mislukte switch wordt de oorspronkelijke directory direct teruggezet.
Bij een mislukte start of healthcheck wordt de nieuwe directory naar
`.platform-failed/<update-id>` verplaatst, de swap teruggezet en de oude
resource opnieuw gestart. De uitkomst wordt `ROLLED_BACK` of `FAILED`.

De bridge schrijft vóór iedere fase atomisch een lokaal updatejournal. Na een
bridge- of serverrestart herstelt hij een achtergebleven swap voordat nieuwe
commando's worden opgehaald. Het journal accepteert alleen paden binnen de
resourceparent en wordt na herstel verwijderd.

## Updatebeleid in het paneel

In **Marketplace → Bibliotheek** heeft iedere installatie:

- beleid `Handmatig` of `Automatisch`;
- kanaal `Stable`, `Beta` of `Development`;
- een bevestigde knop **Nu bijwerken**;
- de laatste status en recente fasegebeurtenissen;
- de bestaande handmatige rollback.

Productionservers mogen alleen stable volgen. Beta is beschikbaar op staging en
development; developmentreleases uitsluitend op developmentservers.
Automatische controle gebeurt tijdens een geauthenticeerde bridge-heartbeat en
plant nooit een tweede actieve update voor dezelfde installatie.

## Audit en gegevensmodel

`MarketplaceResourceUpdate` bewaart organisatie, server, installatie, bron- en
doelversie, trigger, aanvrager, resource, command, healthcheck, paden,
fout-/rollbackreden en timestamps. `MarketplaceResourceUpdateEvent` bewaart
iedere fase met bericht, resultaat en metadata.

Daarnaast schrijft het centrale auditlog afzonderlijke events voor
beleidswijzigingen, handmatige/automatische planning, iedere bridgefase en de
terminale uitkomst. De history-API geeft maximaal vijftig updates met hun
volledige eventvolgorde terug.

## Operationele eisen

- Releasearchives moeten hun FiveM-manifest in de ZIP-root plaatsen.
- De `version` in dat manifest moet exact gelijk zijn aan de marketplaceversie.
- Bridge 0.8.0 of hoger en capability `resource-updater-v1` zijn verplicht.
- De resource moet reeds als marketplace-installatie aan dezelfde server
  gekoppeld zijn.
- Backups en mislukte releases worden bewust behouden voor diagnose; periodieke
  retentie kan later door platformbeheer worden ingesteld zonder de laatste
  herstelkopie te verwijderen.