Guide Host Samsung Tizen - Validation du Contrat Bridge

Objectif

Ce guide est destine a l'agent de code en charge de l'application hote Samsung Tizen.

L'objectif est d'implementer, dans le projet hote Tizen, une validation contractuelle des messages bridge echanges avec l'application Web TVCAST_DISPLAY_WEB.

La validation doit garantir que l'hote Tizen respecte le contrat officiel pour:

les messages recus depuis l'application Web: TV_API_REQUEST
les messages renvoyes a l'application Web: TV_API_RESPONSE
les cas de succes et les cas d'erreur reels de l'hote

Documentation De Reference

Avant toute modification du projet hote Tizen, lire la documentation generale:

text

docs/technique/bridge/contract-validation.md

Cette page decrit le processus complet de validation cote Web et cote Host.

Contexte D'Integration

L'application Web TVCAST_DISPLAY_WEB est chargee par l'application hote Samsung Tizen. Les deux projets communiquent via des messages postMessage standardises.

Sens Web vers Host:

json

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

Sens Host vers Web:

json

{
	"type": "TV_API_RESPONSE",
	"requestId": "req_001",
	"ok": true,
	"payload": {}
}

Le projet hote Tizen doit valider les deux sens avec les schemas officiels.

Source De Verite Du Contrat

Le contrat officiel est maintenu dans le depot prive:

text

comminter/tvcast-display-hosts-api-contracts

Schemas a utiliser:

text

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

Regle stricte: ne jamais modifier localement les schemas officiels dans le projet Tizen pour faire passer une validation. Toute evolution de schema doit etre proposee dans le repo de contrat officiel.

Structure Recommandee Dans Le Projet Tizen

Ajouter un dossier contract/ au projet hote Samsung Tizen:

text

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

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

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

Mapping de validation:

Dossier	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`

Fixtures Web Vers Host

Ajouter une fixture TV_API_REQUEST pour chaque action que l'hote Samsung Tizen sait reellement recevoir.

Actions candidates a couvrir selon l'implementation Tizen reelle:

GET_HOST_CAPABILITIES
GET_IDENTIFIER
GET_NETWORK_INFO
LAUNCH_TV
OPEN_SYSTEM_SETTINGS
OPEN_MANUFACTURER_SETTINGS
PURGE_DATA
REBOOT
INITIALIZE_HOST
APP_IS_FOREGROUND
toute autre action deja supportee par l'hote Tizen

Ne pas creer de fixture de succes pour une action non supportee.

Pour une action non supportee, ajouter plutot une fixture de reponse d'erreur dans host-to-web si ce cas est effectivement gere par l'hote.

Exemple de fixture request:

json

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

Fixtures Host Vers Web

Ajouter une fixture TV_API_RESPONSE pour chaque reponse que l'hote Tizen produit reellement.

Inclure au minimum:

un cas succes par action supportee
les erreurs standardisees produites par l'hote
les reponses de refus ou d'indisponibilite quand elles existent

Codes d'erreur candidats:

UNSUPPORTED_ACTION
INVALID_PARAMS
NOT_AVAILABLE_ON_DEVICE
tout autre code prevu par le contrat officiel et utilise par l'hote Tizen

Exemple de reponse succes:

json

{
	"type": "TV_API_RESPONSE",
	"requestId": "req_capabilities_001",
	"ok": true,
	"payload": {
		"bridgeVersion": "2.0.0",
		"host": {
			"platform": "tizen",
			"vendor": "samsung",
			"model": "Tizen TV",
			"appVersion": "1.0.0"
		},
		"capabilities": {
			"actions": {
				"GET_HOST_CAPABILITIES": true,
				"LAUNCH_TV": true,
				"OPEN_SYSTEM_SETTINGS": true
			}
		}
	}
}

Exemple de reponse erreur:

json

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

Script De Validation Attendu

Creer contract/scripts/validate-contract.mjs dans le projet Tizen.

Le script doit:

Lire la variable CONTRACT_ARTIFACTS_DIR.
Charger les schemas depuis le repo comminter/tvcast-display-hosts-api-contracts.
Valider contract/fixtures/web-to-host/*.json contre le schema TV_API_REQUEST.
Valider contract/fixtures/host-to-web/*.json contre le schema TV_API_RESPONSE.
Afficher des erreurs lisibles par fixture invalide.
Sortir avec le code 1 si une fixture est invalide.
Sortir avec le code 0 si tout est conforme.

Le validateur de TVCAST_DISPLAY_WEB peut etre utilise comme reference:

text

contract/scripts/validate-contract.mjs

Adapter uniquement les chemins de fixtures au projet hote Tizen.

Dependances

Si le projet hote utilise Node/npm, ajouter les dependances de validation JSON Schema:

bash

npm install --save-dev ajv ajv-formats

Si le script npm doit etre compatible Windows et Linux, utiliser aussi cross-env:

bash

npm install --save-dev cross-env

Commandes NPM Recommandees

Ajouter un contract/package.json:

json

{
	"name": "tizen-host-contract-check",
	"version": "1.0.0",
	"private": true,
	"type": "module",
	"scripts": {
		"validate": "node scripts/validate-contract.mjs"
	},
	"devDependencies": {
		"ajv": "^8.17.1",
		"ajv-formats": "^3.0.1"
	}
}

Ajouter une commande a la racine du projet hote:

json

{
	"scripts": {
		"test:contract": "cross-env CONTRACT_ARTIFACTS_DIR=external/tvcast-display-hosts-api-contracts npm run --prefix contract validate"
	}
}

Adapter le chemin CONTRACT_ARTIFACTS_DIR a la structure reelle du repo Tizen.

Workflow GitHub Actions Recommande

Ajouter ou adapter un workflow CI dans le projet hote Tizen.

Exemple:

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

Le secret CONTRACT_REPO_TOKEN doit avoir un acces en lecture au repo de contrat officiel.

Regles De Modification Du Contrat

Si une fixture Tizen represente un comportement necessaire mais refuse par le contrat officiel:

Ne pas modifier les schemas dans le repo Tizen.
Ne pas assouplir le validateur pour ignorer l'erreur.
Identifier l'ecart exact entre le comportement Tizen et le contrat.
Proposer une evolution dans comminter/tvcast-display-hosts-api-contracts.
Attendre l'acceptation et le versionnement du contrat.
Mettre a jour CONTRACT_VERSION dans le projet Tizen.
Relancer la validation contractuelle.

Verification Locale Attendue

Depuis la racine du projet hote Tizen:

bash

npm run test:contract

Resultat attendu:

text

Validated X web-to-host TV_API_REQUEST fixture(s)
Validated Y host-to-web TV_API_RESPONSE fixture(s)
Contract validation passed.

Le texte exact peut varier selon le script, mais la commande doit echouer en cas de fixture invalide.

Livrables Attendus

L'agent Tizen doit livrer:

un dossier contract/ ajoute ou mis a jour
des fixtures JSON pour les requetes Web vers Host
des fixtures JSON pour les reponses Host vers Web
un script de validation contractuelle
une commande npm test:contract
un workflow GitHub Actions ou une integration dans la CI existante
une documentation courte dans le repo Tizen expliquant comment lancer la validation
un rapport final listant les actions Tizen couvertes
un rapport final listant les fixtures ajoutees
un rapport final indiquant le resultat de npm run test:contract
un rapport final listant les ecarts necessitant une evolution du contrat officiel, s'il y en a

Checklist Finale

Avant livraison, verifier:

chaque fixture represente un message reellement recu ou envoye par l'hote Tizen
les fixtures web-to-host sont validees contre TV_API_REQUEST
les fixtures host-to-web sont validees contre TV_API_RESPONSE
les erreurs standardisees sont couvertes
la commande locale passe
la CI execute la validation
le repo de contrat est pinne via CONTRACT_VERSION
aucun schema officiel n'a ete modifie localement

Message Important Pour L'Agent

Le but n'est pas seulement de faire passer la CI. Les fixtures doivent representer fidelement les messages vraiment recus et envoyes par l'application hote Samsung Tizen.

Une validation qui passe avec des fixtures artificielles ou incompletes ne garantit pas la conformite du bridge.

Guide Host Samsung Tizen - Validation du Contrat Bridge ​

Objectif ​

Documentation De Reference ​

Contexte D'Integration ​

Source De Verite Du Contrat ​

Structure Recommandee Dans Le Projet Tizen ​

Fixtures Web Vers Host ​

Fixtures Host Vers Web ​

Script De Validation Attendu ​

Dependances ​

Commandes NPM Recommandees ​

Workflow GitHub Actions Recommande ​

Regles De Modification Du Contrat ​

Verification Locale Attendue ​

Livrables Attendus ​

Checklist Finale ​

Message Important Pour L'Agent ​

Guide Host Samsung Tizen - Validation du Contrat Bridge

Objectif

Documentation De Reference

Contexte D'Integration

Source De Verite Du Contrat

Structure Recommandee Dans Le Projet Tizen

Fixtures Web Vers Host

Fixtures Host Vers Web

Script De Validation Attendu

Dependances

Commandes NPM Recommandees

Workflow GitHub Actions Recommande

Regles De Modification Du Contrat

Verification Locale Attendue

Livrables Attendus

Checklist Finale

Message Important Pour L'Agent