Validation du Contrat Bridge

Objectif

Ce document decrit le processus de validation du contrat bridge entre l'application Web TVCAST_DISPLAY_WEB et les applications hotes qui chargent cette application Web.

Il doit pouvoir etre reutilise par les agents de code et les equipes en charge des hotes LG, Tizen, Android, Philips ou tout autre wrapper natif.

Le but est d'empecher qu'un projet Web ou Host introduise une regression dans les messages TV_API_REQUEST et TV_API_RESPONSE.

Architecture

L'application Web est chargee par une application hote. Les deux projets communiquent avec des messages postMessage standardises.

Le repo de contrat est la source de verite commune. Aucun projet applicatif ne doit modifier une copie locale des schemas pour contourner une erreur de validation.

Source de Verite

Le contrat officiel est maintenu dans le depot prive suivant:

text

comminter/tvcast-display-hosts-api-contracts

Ce depot contient les JSON Schemas qui definissent les enveloppes et payloads autorises.

Schemas actuellement utilises par l'application Web:

text

schemas/envelope/request.schema.json
schemas/envelope/response.schema.json

Le workflow CI checkout ce repo a une revision fixe via CONTRACT_VERSION. Cette revision doit etre mise a jour volontairement lorsqu'une nouvelle version du contrat est adoptee.

Ce Qui Est Valide

La validation verifie les exemples JSON versionnes dans chaque projet, appeles fixtures.

Cote Web, le controle couvre:

les messages envoyes par l'application Web vers l'hote: TV_API_REQUEST
les messages attendus par l'application Web depuis l'hote: TV_API_RESPONSE
les champs obligatoires de l'enveloppe: type, requestId, action, params, ok, payload
les payloads specifiques aux actions supportees par les schemas officiels
les cas de succes et les cas d'erreur standardises

Cote Host, le controle doit couvrir les memes echanges, vus du point de vue de l'hote:

les messages recus depuis l'application Web: TV_API_REQUEST
les messages envoyes par l'hote vers l'application Web: TV_API_RESPONSE
les actions reellement supportees par l'hote
les erreurs que l'hote peut produire: UNSUPPORTED_ACTION, INVALID_PARAMS, NOT_AVAILABLE_ON_DEVICE, etc.

Implementation Dans TVCAST_DISPLAY_WEB

Dans ce projet, la validation est portee par le dossier suivant:

text

contract/
├── fixtures/
│   ├── outbound-requests/
│   └── inbound-responses/
├── package.json
└── scripts/
    └── validate-contract.mjs

Les fixtures outbound-requests representent ce que l'application Web envoie aux hotes.

Les fixtures inbound-responses representent ce que l'application Web accepte en retour des hotes.

Le script contract/scripts/validate-contract.mjs:

lit CONTRACT_ARTIFACTS_DIR
detecte le repo de contrat checkout localement ou en CI
charge les schemas JSON disponibles sous schemas/
selectionne le schema TV_API_REQUEST
selectionne le schema TV_API_RESPONSE
valide toutes les fixtures Web contre ces schemas
affiche les erreurs AJV par fixture invalide
retourne un code d'erreur non nul si une fixture ne respecte pas le contrat

Commande Locale Cote Web

Depuis la racine de TVCAST_DISPLAY_WEB:

bash

npm run test:contract

Cette commande execute:

bash

cross-env CONTRACT_ARTIFACTS_DIR=external/tvcast-display-hosts-api-contracts npm run --prefix contract validate

Le validateur accepte plusieurs emplacements pour le repo de contrat:

TVCAST_DISPLAY_WEB/external/tvcast-display-hosts-api-contracts
un chemin absolu fourni par CONTRACT_ARTIFACTS_DIR
un checkout voisin du projet Web, par exemple external/tvcast-display-hosts-api-contracts a cote de TVCAST_DISPLAY_WEB

Exemple avec un chemin explicite:

bash

npx cross-env CONTRACT_ARTIFACTS_DIR=../tvcast-display-hosts-api-contracts npm run --prefix contract validate

CI GitHub Actions Cote Web

Le workflow dedie est:

text

.github/workflows/contract-check.yml

Il effectue les operations suivantes:

Checkout du repo applicatif Web.
Checkout du repo comminter/tvcast-display-hosts-api-contracts a la revision CONTRACT_VERSION.
Installation des dependances du dossier contract/.
Execution de npm run validate dans contract/.

Variables importantes:

yaml

CONTRACT_VERSION: <commit du repo contrat>
CONTRACT_REPOSITORY: comminter/tvcast-display-hosts-api-contracts
CONTRACT_ARTIFACTS_DIR: contract-artifacts

Secret requis:

text

CONTRACT_REPO_TOKEN

Le token doit avoir un acces en lecture au repo de contrat.

Structure Recommandee Pour Une Application Hote

Les applications hotes doivent implementer une validation similaire. La structure recommandee est volontairement independante du point de vue inbound ou outbound, car ces mots changent de sens entre Web et Host.

text

contract/
├── fixtures/
│   ├── web-to-host/
│   └── host-to-web/
├── package.json
└── scripts/
    └── validate-contract.mjs

web-to-host contient les requetes que l'hote sait recevoir depuis l'application Web.

host-to-web contient les reponses que l'hote sait renvoyer a l'application Web.

Mapping de validation:

Dossier Host	Type attendu	Schema officiel
`contract/fixtures/web-to-host/`	`TV_API_REQUEST`	`schemas/envelope/request.schema.json`
`contract/fixtures/host-to-web/`	`TV_API_RESPONSE`	`schemas/envelope/response.schema.json`

Les hotes peuvent reprendre le validateur Web comme base, mais doivent adapter les dossiers de fixtures et les scripts npm a leur structure projet.

Exemple De Fixture Request

json

{
	"type": "TV_API_REQUEST",
	"requestId": "req_capabilities_001",
	"action": "GET_HOST_CAPABILITIES",
	"params": {}
}

Exemple De Fixture Response Succes

json

{
	"type": "TV_API_RESPONSE",
	"requestId": "req_capabilities_001",
	"ok": true,
	"payload": {
		"bridgeVersion": "2.0.0",
		"host": {
			"platform": "android",
			"vendor": "philips",
			"model": "65HFL6214U",
			"appVersion": "1.0.0"
		},
		"capabilities": {
			"actions": {
				"GET_HOST_CAPABILITIES": true,
				"LAUNCH_TV": true,
				"OPEN_SYSTEM_SETTINGS": true
			}
		}
	}
}

Exemple De Fixture Response Erreur

json

{
	"type": "TV_API_RESPONSE",
	"requestId": "req_unknown_001",
	"ok": false,
	"payload": {
		"code": "UNSUPPORTED_ACTION",
		"message": "Unsupported action: UNKNOWN_ACTION"
	}
}

Ajouter Ou Modifier Une Action Bridge

Toute evolution d'action bridge doit suivre cet ordre.

Identifier si l'action existe deja dans le repo de contrat.
Si le schema officiel ne couvre pas le besoin, ouvrir d'abord une modification dans comminter/tvcast-display-hosts-api-contracts.
Attendre que la modification du contrat soit acceptee et versionnee.
Mettre a jour l'implementation Web ou Host.
Ajouter ou modifier les fixtures locales.
Lancer la validation contractuelle localement.
Mettre a jour CONTRACT_VERSION dans la CI si une nouvelle revision du contrat est requise.
Ouvrir la PR applicative uniquement quand la validation passe.

Il est interdit de faire diverger les schemas localement pour faire passer une PR applicative. Le repo de contrat est la source de verite.

Checklist Pour Agents De Code

Pour ajouter la validation dans un projet hote, appliquer cette checklist:

Ajouter un dossier contract/ dans le projet hote.
Ajouter les dependances de validation JSON Schema, par exemple ajv et ajv-formats.
Ajouter une commande npm, par exemple test:contract.
Checkout le repo comminter/tvcast-display-hosts-api-contracts localement ou en CI.
Ajouter des fixtures web-to-host pour chaque TV_API_REQUEST supportee.
Ajouter des fixtures host-to-web pour chaque TV_API_RESPONSE produite.
Valider web-to-host contre le schema request officiel.
Valider host-to-web contre le schema response officiel.
Ajouter un workflow CI qui execute la commande de validation.
Bloquer les merges si le check contractuel echoue.
Ne jamais modifier le contrat officiel depuis le projet hote directement.
Documenter les actions non supportees et les codes d'erreur retournes.

Exemple Minimal De Workflow Host

yaml

name: Contract Check

on:
  pull_request:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  contract-check:
    runs-on: self-hosted
    env:
      CONTRACT_VERSION: <commit-du-repo-contrat>
      CONTRACT_REPOSITORY: comminter/tvcast-display-hosts-api-contracts
      CONTRACT_ARTIFACTS_DIR: contract-artifacts
    steps:
      - name: Checkout host repository
        uses: actions/checkout@v4

      - name: Checkout contract repository at version
        uses: actions/checkout@v4
        with:
          repository: ${{ env.CONTRACT_REPOSITORY }}
          ref: ${{ env.CONTRACT_VERSION }}
          path: ${{ env.CONTRACT_ARTIFACTS_DIR }}
          token: ${{ secrets.CONTRACT_REPO_TOKEN }}

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci --no-fund --no-audit

      - name: Validate bridge contract fixtures
        run: npm run test:contract

Erreurs Frequentes

`CONTRACT_ARTIFACTS_DIR is required`

La variable d'environnement n'est pas definie. Definir un chemin vers le checkout du repo de contrat.

`Contract artifacts directory not found`

Le chemin fourni ne pointe pas vers un dossier existant. Verifier le checkout local ou l'etape GitHub Actions qui recupere le repo de contrat.

`No JSON schemas found`

Le dossier de contrat est vide ou ne contient pas les schemas attendus. Verifier que le repo checkout est bien comminter/tvcast-display-hosts-api-contracts et que la revision CONTRACT_VERSION est correcte.

`Unable to find a schema for TV_API_REQUEST`

Le validateur ne trouve pas le schema de requete. Verifier l'emplacement et le contenu des schemas du repo de contrat.

`Contract validation failed`

Une ou plusieurs fixtures ne respectent pas les schemas officiels. Corriger la fixture ou, si le besoin est legitime, faire evoluer le repo de contrat avant de modifier le projet applicatif.

Strategie De Versionnement

Chaque CI doit pinner une revision du repo de contrat via CONTRACT_VERSION.

Cette strategie evite qu'une modification du contrat casse immediatement tous les projets consommateurs.

Lorsqu'une nouvelle revision du contrat est adoptee:

Mettre a jour CONTRACT_VERSION dans le projet Web ou Host.
Lancer la validation locale.
Corriger les fixtures si necessaire.
Ouvrir une PR dediee ou inclure le changement dans la PR de fonctionnalite si les deux sont inseparables.

Definition Of Done

Une integration bridge est consideree conforme lorsque:

le code implemente les actions attendues
les fixtures representent les messages reels envoyes et recus
la validation contractuelle passe localement
la CI execute la validation sur chaque PR
les merges vers main sont bloques si la validation echoue
toute evolution de schema est d'abord acceptee dans le repo de contrat officiel

References

contract/README.md
.github/workflows/contract-check.yml
contract/scripts/validate-contract.mjs
docs/technique/bridge/contract-gap-analysis.md
docs/technique/bridge/contract-check-branch-protection.md
docs/technique/bridge/exchanges.md
docs/technique/bridge/host-tizen-contract-validation-guide.md

Validation du Contrat Bridge ​

Objectif ​

Architecture ​

Source de Verite ​

Ce Qui Est Valide ​

Implementation Dans TVCAST_DISPLAY_WEB ​

Commande Locale Cote Web ​

CI GitHub Actions Cote Web ​

Structure Recommandee Pour Une Application Hote ​

Exemple De Fixture Request ​

Exemple De Fixture Response Succes ​

Exemple De Fixture Response Erreur ​

Ajouter Ou Modifier Une Action Bridge ​

Checklist Pour Agents De Code ​

Exemple Minimal De Workflow Host ​

Erreurs Frequentes ​

CONTRACT_ARTIFACTS_DIR is required ​

Contract artifacts directory not found ​

No JSON schemas found ​

Unable to find a schema for TV_API_REQUEST ​

Contract validation failed ​

Strategie De Versionnement ​

Definition Of Done ​

References ​

Validation du Contrat Bridge

Objectif

Architecture

Source de Verite

Ce Qui Est Valide

Implementation Dans TVCAST_DISPLAY_WEB

Commande Locale Cote Web

CI GitHub Actions Cote Web

Structure Recommandee Pour Une Application Hote

Exemple De Fixture Request

Exemple De Fixture Response Succes

Exemple De Fixture Response Erreur

Ajouter Ou Modifier Une Action Bridge

Checklist Pour Agents De Code

Exemple Minimal De Workflow Host

Erreurs Frequentes

`CONTRACT_ARTIFACTS_DIR is required`

`Contract artifacts directory not found`

`No JSON schemas found`

`Unable to find a schema for TV_API_REQUEST`

`Contract validation failed`

Strategie De Versionnement

Definition Of Done

References