04 – Configuration

Version : 4.0.0 Date : 2025-01-25

1. Introduction

Le Socle V4 utilise une configuration centralisée via SocleConfiguration qui charge les paramètres depuis application.yml et les variables d’environnement.

Priorité de configuration

1. Variables d'environnement (priorité maximale)
2. application.yml
3. Valeurs par défaut dans le code

2. Fichier application.yml

2.1 Configuration minimale

socle:
  app_name: ${APP_NAME:my-app}
  env_name: ${ENV_NAME:DEV}
  exec_id: ${EXEC_ID:${socle.app_name}-${random.uuid}}
  region: ${REGION:local}
  version: ${APP_VERSION:4.0.0}

spring:
  application:
    name: ${socle.app_name}

server:
  port: ${HTTP_PORT:8080}

logging:
  config: classpath:log4j2.xml

2.2 Configuration complète

socle:
  # === Identification ===
  app_name: ${APP_NAME:socle-v4}
  env_name: ${ENV_NAME:DEV}
  exec_id: ${EXEC_ID:${socle.app_name}-${random.uuid}}
  region: ${REGION:local}
  version: ${APP_VERSION:4.0.0}

  # === HTTP Server ===
  http:
    enabled: ${HTTP_ENABLED:true}
    port: ${HTTP_PORT:8080}
    context-path: ${CONTEXT_PATH:/}

  # === KvBus ===
  kvbus:
    mode: ${KVBUS_MODE:in_memory}
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
      password: ${REDIS_PASSWORD:}
      database: ${REDIS_DATABASE:0}
      prefix: ${REDIS_PREFIX:socle}

  # === Supervisor ===
  supervisor:
    heartbeat-interval-ms: ${SUPERVISOR_HEARTBEAT_MS:10000}
    unhealthy-threshold: ${SUPERVISOR_UNHEALTHY_THRESHOLD:3}
    check-interval-ms: ${SUPERVISOR_CHECK_INTERVAL_MS:5000}
    stale-timeout-ms: ${SUPERVISOR_STALE_TIMEOUT_MS:60000}

  # === StatusDashboard (V4) ===
  status_dashboard:
    enabled: ${STATUS_DASHBOARD_ENABLED:true}
    port: ${STATUS_DASHBOARD_PORT:9374}
    refresh_interval: ${STATUS_DASHBOARD_REFRESH:5}

  # === Scheduler ===
  scheduler:
    enabled: ${SCHEDULER_ENABLED:true}
    thread-pool-size: ${SCHEDULER_POOL_SIZE:4}

  # === Admin API ===
  admin:
    enabled: ${ADMIN_ENABLED:true}
    auth:
      enabled: ${ADMIN_AUTH_ENABLED:false}
      username: ${ADMIN_USERNAME:admin}
      password: ${ADMIN_PASSWORD:admin}

  # === TechDB (V4) ===
  techdb:
    enabled: ${TECHDB_ENABLED:true}
    url: jdbc:h2:file:${TECHDB_PATH:./data/socle-techdb};MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    username: socle
    password: ${TECHDB_PASSWORD:socle}
    console:
      enabled: ${H2_CONSOLE_ENABLED:false}
      path: /h2-console

  # === Logging (V4) ===
  logging:
    forwarder:
      enabled: ${LOG_FORWARDER_ENABLED:false}
      transport-mode: ${LOG_TRANSPORT_MODE:http}
      log-hub-url: ${LOG_HUB_URL:}
      nats-url: ${NATS_URL:}
      batch-size: ${LOG_BATCH_SIZE:100}
      flush-interval-ms: ${LOG_FLUSH_INTERVAL_MS:5000}

  # === Auth Client (V4) ===
  auth:
    enabled: ${AUTH_ENABLED:false}
    server-url: ${AUTH_SERVER_URL:}
    source-name: ${SOURCE_NAME:${socle.app_name}}
    api-key: ${API_KEY:}

  # === Worker Registry (V4) ===
  worker-registry:
    enabled: ${WORKER_REGISTRY_ENABLED:false}
    server-url: ${WORKER_REGISTRY_URL:}
    heartbeat-interval-ms: ${REGISTRY_HEARTBEAT_MS:30000}

spring:
  application:
    name: ${socle.app_name}

server:
  port: ${socle.http.port}

logging:
  config: classpath:log4j2.xml

3. Variables d’environnement

3.1 Variables essentielles

Variable	Description	Défaut	Obligatoire
APP_NAME	Nom de l’application	socle-v4	Recommandé
ENV_NAME	Environnement (DEV/STAGING/PROD)	DEV	Recommandé
REGION	Région géographique	local	Recommandé
HTTP_PORT	Port HTTP	8080	Non

3.2 Variables KvBus

Variable	Description	Défaut
KVBUS_MODE	Mode (in_memory/redis)	in_memory
REDIS_HOST	Hôte Redis	localhost
REDIS_PORT	Port Redis	6379
REDIS_PASSWORD	Mot de passe Redis	–
REDIS_DATABASE	Database Redis	0
REDIS_PREFIX	Préfixe des clés	socle

3.3 Variables Supervisor et Dashboard

Variable	Description	Défaut
SUPERVISOR_HEARTBEAT_MS	Intervalle heartbeat attendu	10000 (10s)
SUPERVISOR_UNHEALTHY_THRESHOLD	Heartbeats manqués avant UNHEALTHY	3
SUPERVISOR_CHECK_INTERVAL_MS	Fréquence de vérification	5000 (5s)
SUPERVISOR_STALE_TIMEOUT_MS	Timeout avant STALE	60000 (1min)
STATUS_DASHBOARD_ENABLED	Activer le dashboard	true
STATUS_DASHBOARD_PORT	Port du dashboard	9374
STATUS_DASHBOARD_REFRESH	Rafraîchissement (secondes)	5

3.4 Variables V4

Variable	Description	Défaut
TECHDB_ENABLED	Activer H2 TechDB	true
TECHDB_PATH	Chemin fichier H2	./data/socle-techdb
H2_CONSOLE_ENABLED	Console H2 web	false
LOG_FORWARDER_ENABLED	Activer LogForwarder	false
LOG_TRANSPORT_MODE	Mode transport logs	http
AUTH_ENABLED	Activer auth JWT	false
WORKER_REGISTRY_ENABLED	Activer registry	false

4. Classe SocleConfiguration

package eu.lmvi.socle.config;

@Configuration
@ConfigurationProperties(prefix = "socle")
public class SocleConfiguration {

    // === Identification ===
    private String app_name = "socle-v4";
    private String env_name = "DEV";
    private String exec_id;
    private String region = "local";
    private String version = "4.0.0";

    // === HTTP ===
    private HttpConfig http = new HttpConfig();

    // === KvBus ===
    private KvBusConfig kvbus = new KvBusConfig();

    // === Supervisor ===
    private SupervisorConfig supervisor = new SupervisorConfig();

    // === TechDB (V4) ===
    private TechDbConfig techdb = new TechDbConfig();

    // === Logging (V4) ===
    private LoggingConfig logging = new LoggingConfig();

    // === Auth (V4) ===
    private AuthConfig auth = new AuthConfig();

    // === Worker Registry (V4) ===
    private WorkerRegistryConfig workerRegistry = new WorkerRegistryConfig();

    // Getters / Setters...

    @PostConstruct
    public void init() {
        if (exec_id == null || exec_id.isEmpty()) {
            exec_id = app_name + "-" + UUID.randomUUID().toString().substring(0, 8);
        }
    }
}

4.1 Sous-configurations

public static class HttpConfig {
    private boolean enabled = true;
    private int port = 8080;
    private String contextPath = "/";
}

public static class KvBusConfig {
    private String mode = "in_memory";
    private RedisConfig redis = new RedisConfig();
}

public static class TechDbConfig {
    private boolean enabled = true;
    private String url = "jdbc:h2:file:./data/socle-techdb";
    private String username = "socle";
    private String password = "socle";
    private ConsoleConfig console = new ConsoleConfig();
}

public static class LoggingConfig {
    private ForwarderConfig forwarder = new ForwarderConfig();
}

public static class AuthConfig {
    private boolean enabled = false;
    private String serverUrl;
    private String sourceName;
    private String apiKey;
}

public static class WorkerRegistryConfig {
    private boolean enabled = false;
    private String serverUrl;
    private long heartbeatIntervalMs = 30000;
}

5. Accès à la configuration

5.1 Injection

@Service
public class MonService {

    @Autowired
    private SocleConfiguration config;

    public void doSomething() {
        String appName = config.getApp_name();
        String region = config.getRegion();
        boolean techDbEnabled = config.getTechdb().isEnabled();
    }
}

5.2 Dans un Worker

public class MonWorker implements Worker {

    private final SocleConfiguration config;

    public MonWorker(SocleConfiguration config) {
        this.config = config;
    }

    @Override
    public void doWork() {
        log.info("Running in region: {}", config.getRegion());
    }
}

6. Profils Spring

6.1 Activation

# Via variable d'environnement
export SPRING_PROFILES_ACTIVE=prod

# Via ligne de commande
java -jar app.jar --spring.profiles.active=prod

6.2 Fichiers par profil

src/main/resources/
├── application.yml           # Configuration de base
├── application-dev.yml       # Overrides DEV
├── application-staging.yml   # Overrides STAGING
└── application-prod.yml      # Overrides PROD

6.3 Exemple application-prod.yml

socle:
  env_name: PROD
  techdb:
    console:
      enabled: false
  logging:
    forwarder:
      enabled: true
  auth:
    enabled: true
  worker-registry:
    enabled: true

logging:
  config: classpath:log4j2-prod.xml

7. Configuration Docker

7.1 Dockerfile

FROM eclipse-temurin:21-jre

WORKDIR /app

COPY target/socle-v004-4.0.0.jar app.jar

# Variables par défaut (peuvent être overridées)
ENV APP_NAME=socle-v4
ENV ENV_NAME=PROD
ENV HTTP_PORT=8080
ENV TECHDB_PATH=/app/data/techdb

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "app.jar"]

7.2 docker-compose.yml

version: '3.8'

services:
  socle-app:
    image: socle-v4:latest
    environment:
      - APP_NAME=my-service
      - ENV_NAME=PROD
      - REGION=MTQ
      - KVBUS_MODE=redis
      - REDIS_HOST=redis
      - LOG_FORWARDER_ENABLED=true
      - LOG_HUB_URL=http://loghub:8080/api/ingest-logs
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

8. Configuration Kubernetes

8.1 ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: socle-config
data:
  APP_NAME: "my-service"
  ENV_NAME: "PROD"
  REGION: "MTQ"
  KVBUS_MODE: "redis"
  LOG_FORWARDER_ENABLED: "true"

8.2 Secret

apiVersion: v1
kind: Secret
metadata:
  name: socle-secrets
type: Opaque
stringData:
  REDIS_PASSWORD: "secret-password"
  API_KEY: "my-api-key"
  TECHDB_PASSWORD: "techdb-password"

8.3 Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: socle-app
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: socle
          image: socle-v4:latest
          envFrom:
            - configMapRef:
                name: socle-config
            - secretRef:
                name: socle-secrets
          ports:
            - containerPort: 8080

9. Validation de configuration

9.1 Validation au démarrage

@Component
public class ConfigurationValidator implements ApplicationListener<ApplicationReadyEvent> {

    @Autowired
    private SocleConfiguration config;

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        validateRequired();
        validateConsistency();
    }

    private void validateRequired() {
        if (config.getApp_name() == null || config.getApp_name().isEmpty()) {
            throw new IllegalStateException("APP_NAME is required");
        }
    }

    private void validateConsistency() {
        if (config.getAuth().isEnabled() && config.getAuth().getApiKey() == null) {
            throw new IllegalStateException("API_KEY required when AUTH_ENABLED=true");
        }
    }
}

9.2 Endpoint de configuration

GET /admin/config

Retourne la configuration actuelle (sans les secrets).

10. Bonnes pratiques

DO

• Utiliser les variables d’environnement pour les valeurs spécifiques à l’environnement
• Définir des valeurs par défaut sensées
• Utiliser des profils Spring pour les environnements
• Valider la configuration au démarrage
• Ne jamais committer de secrets

DON’T

• Ne pas hardcoder de valeurs dans le code
• Ne pas mettre de mots de passe dans application.yml
• Ne pas utiliser de valeurs par défaut dangereuses en prod

11. Références

• 02-ARCHITECTURE
• 03-QUICKSTART
• 08-SUPERVISOR – Supervision et heartbeats
• 21-H2-TECHDB
• 27-STATUS-DASHBOARD – Dashboard supervision
• GUIDE-METHODOLOGIQUE – Bonnes pratiques
• Spring Boot Configuration

03 – Guide de Démarrage Rapide

Version : 4.0.0 Date : 2025-01-25 Temps estimé : 5 minutes

1. Prérequis

• JDK 21+ installé
• Maven 3.9+ installé
• Git (optionnel)

Vérification :

java -version   # java version "21.x.x"
mvn -version    # Maven 3.9.x

2. Installation

Option A : Cloner le projet

git clone <repo>/socle-v004.git
cd socle-v004

Option B : Créer un nouveau projet

mvn archetype:generate \
  -DgroupId=com.mycompany \
  -DartifactId=my-socle-app \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

cd my-socle-app
# Ajouter la dépendance socle-v004 dans pom.xml

3. Configuration minimale

3.1 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>eu.lmvi</groupId>
    <artifactId>socle-v004</artifactId>
    <version>4.0.0</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.1</version>
    </parent>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Web (sans Logback) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-logging</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- Log4j2 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-log4j2</artifactId>
        </dependency>

        <!-- LMAX Disruptor (AsyncLoggers) -->
        <dependency>
            <groupId>com.lmax</groupId>
            <artifactId>disruptor</artifactId>
            <version>4.0.0</version>
        </dependency>

        <!-- H2 Database -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>2.2.224</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

3.2 application.yml

spring:
  application:
    name: my-socle-app

socle:
  app_name: ${APP_NAME:my-socle-app}
  version: 4.0.0
  env_name: ${ENV_NAME:DEV}
  region: ${REGION:local}

  # HTTP
  http_port: ${HTTP_PORT:8080}

  # KV Bus
  kv_impl: in_memory

  # Supervisor
  supervisor_enabled: true

  # H2 TechDB
  techdb:
    enabled: true
    url: jdbc:h2:file:./data/techdb;MODE=PostgreSQL
    console:
      enabled: true
      path: /h2-console

logging:
  config: classpath:log4j2.xml

3.3 log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

4. Créer un Worker simple

package com.mycompany.worker;

import eu.lmvi.socle.worker.Worker;
import eu.lmvi.socle.supervisor.Supervisor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
public class HelloWorker implements Worker {

    private static final Logger log = LoggerFactory.getLogger(HelloWorker.class);

    @Autowired
    private Supervisor supervisor;  // Injection du Supervisor

    private int counter = 0;
    private volatile boolean running = false;

    @Override
    public String getName() {
        return "hello-worker";
    }

    @Override
    public void initialize() {
        log.info("HelloWorker initializing...");
    }

    @Override
    public void start() {
        running = true;
        log.info("HelloWorker started!");
    }

    @Override
    public void doWork() {
        if (!running) return;  // Vérifier le flag d'arrêt

        try {
            counter++;
            log.info("Hello from worker! Count: {}", counter);

            // IMPORTANT: Envoyer un heartbeat avec métriques
            supervisor.heartbeat(getName(), getStats());

        } catch (Exception e) {
            log.error("Erreur dans doWork", e);
            // NE PAS propager l'exception
        }
    }

    @Override
    public void stop() {
        running = false;
        log.info("HelloWorker stopped. Final count: {}", counter);
    }

    @Override
    public boolean isHealthy() {
        return running;
    }

    @Override
    public Map<String, Object> getStats() {
        return Map.of(
            "counter", counter,
            "running", running
        );
    }

    @Override
    public long getCycleIntervalMs() {
        return 5000; // doWork() toutes les 5 secondes
    }
}

5. Build et Run

# Build
mvn clean package -DskipTests

# Run
java -jar target/socle-v004-4.0.0.jar

# Ou avec variables d'environnement
APP_NAME=my-app ENV_NAME=PROD java -jar target/socle-v004-4.0.0.jar

6. Vérification

Health check

curl http://localhost:8080/health

Réponse attendue :

{
  "status": "UP",
  "app": "my-socle-app",
  "version": "4.0.0"
}

H2 Console (dev)

Ouvrir : http://localhost:8080/h2-console

• JDBC URL : jdbc:h2:file:./data/techdb
• User : socle
• Password : socle

Logs

Vous devriez voir :

INFO  [main] MainOrchestratorProcess - MOP démarré
INFO  [main] HelloWorker - HelloWorker started!
INFO  [scheduler-1] HelloWorker - Hello from worker! Count: 1
INFO  [scheduler-1] HelloWorker - Hello from worker! Count: 2

StatusDashboard (supervision)

Ouvrir : http://localhost:9374/

Ce dashboard affiche en temps réel :

• L’état de chaque worker (RUNNING, DEGRADED, UNHEALTHY)
• Les métriques transmises par les heartbeats
• L’historique des changements d’état

7. Prochaines étapes

Document	Description
04-CONFIGURATION	Configuration complète
05-WORKERS	Guide des Workers
08-SUPERVISOR	Supervision et heartbeats
21-H2-TECHDB	Base H2 TechDB
22-LOG4J2-LOGFORWARDER	Logging centralisé
27-STATUS-DASHBOARD	Dashboard de supervision
GUIDE-METHODOLOGIQUE	Bonnes pratiques

8. Troubleshooting

Port déjà utilisé

# Changer le port
HTTP_PORT=9090 java -jar target/socle-v004-4.0.0.jar

H2 Console inaccessible

Vérifier que socle.techdb.console.enabled: true dans application.yml.

Logs non visibles

Vérifier que log4j2.xml existe dans src/main/resources/.

04 – Configuration

Version : 4.0.0 Date : 2025-01-25

1. Introduction

Le Socle V4 utilise une configuration centralisée via SocleConfiguration qui charge les paramètres depuis application.yml et les variables d’environnement.

Priorité de configuration

1. Variables d'environnement (priorité maximale)
2. application.yml
3. Valeurs par défaut dans le code

2. Fichier application.yml

2.1 Configuration minimale

socle:
  app_name: ${APP_NAME:my-app}
  env_name: ${ENV_NAME:DEV}
  exec_id: ${EXEC_ID:${socle.app_name}-${random.uuid}}
  region: ${REGION:local}
  version: ${APP_VERSION:4.0.0}

spring:
  application:
    name: ${socle.app_name}

server:
  port: ${HTTP_PORT:8080}

logging:
  config: classpath:log4j2.xml

2.2 Configuration complète

socle:
  # === Identification ===
  app_name: ${APP_NAME:socle-v4}
  env_name: ${ENV_NAME:DEV}
  exec_id: ${EXEC_ID:${socle.app_name}-${random.uuid}}
  region: ${REGION:local}
  version: ${APP_VERSION:4.0.0}

  # === HTTP Server ===
  http:
    enabled: ${HTTP_ENABLED:true}
    port: ${HTTP_PORT:8080}
    context-path: ${CONTEXT_PATH:/}

  # === KvBus ===
  kvbus:
    mode: ${KVBUS_MODE:in_memory}
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
      password: ${REDIS_PASSWORD:}
      database: ${REDIS_DATABASE:0}
      prefix: ${REDIS_PREFIX:socle}

  # === Supervisor ===
  supervisor:
    heartbeat-interval-ms: ${SUPERVISOR_HEARTBEAT_MS:10000}
    unhealthy-threshold: ${SUPERVISOR_UNHEALTHY_THRESHOLD:3}
    check-interval-ms: ${SUPERVISOR_CHECK_INTERVAL_MS:5000}
    stale-timeout-ms: ${SUPERVISOR_STALE_TIMEOUT_MS:60000}

  # === StatusDashboard (V4) ===
  status_dashboard:
    enabled: ${STATUS_DASHBOARD_ENABLED:true}
    port: ${STATUS_DASHBOARD_PORT:9374}
    refresh_interval: ${STATUS_DASHBOARD_REFRESH:5}

  # === Scheduler ===
  scheduler:
    enabled: ${SCHEDULER_ENABLED:true}
    thread-pool-size: ${SCHEDULER_POOL_SIZE:4}

  # === Admin API ===
  admin:
    enabled: ${ADMIN_ENABLED:true}
    auth:
      enabled: ${ADMIN_AUTH_ENABLED:false}
      username: ${ADMIN_USERNAME:admin}
      password: ${ADMIN_PASSWORD:admin}

  # === TechDB (V4) ===
  techdb:
    enabled: ${TECHDB_ENABLED:true}
    url: jdbc:h2:file:${TECHDB_PATH:./data/socle-techdb};MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    username: socle
    password: ${TECHDB_PASSWORD:socle}
    console:
      enabled: ${H2_CONSOLE_ENABLED:false}
      path: /h2-console

  # === Logging (V4) ===
  logging:
    forwarder:
      enabled: ${LOG_FORWARDER_ENABLED:false}
      transport-mode: ${LOG_TRANSPORT_MODE:http}
      log-hub-url: ${LOG_HUB_URL:}
      nats-url: ${NATS_URL:}
      batch-size: ${LOG_BATCH_SIZE:100}
      flush-interval-ms: ${LOG_FLUSH_INTERVAL_MS:5000}

  # === Auth Client (V4) ===
  auth:
    enabled: ${AUTH_ENABLED:false}
    server-url: ${AUTH_SERVER_URL:}
    source-name: ${SOURCE_NAME:${socle.app_name}}
    api-key: ${API_KEY:}

  # === Worker Registry (V4) ===
  worker-registry:
    enabled: ${WORKER_REGISTRY_ENABLED:false}
    server-url: ${WORKER_REGISTRY_URL:}
    heartbeat-interval-ms: ${REGISTRY_HEARTBEAT_MS:30000}

spring:
  application:
    name: ${socle.app_name}

server:
  port: ${socle.http.port}

logging:
  config: classpath:log4j2.xml

3. Variables d’environnement

3.1 Variables essentielles

Variable	Description	Défaut	Obligatoire
APP_NAME	Nom de l’application	socle-v4	Recommandé
ENV_NAME	Environnement (DEV/STAGING/PROD)	DEV	Recommandé
REGION	Région géographique	local	Recommandé
HTTP_PORT	Port HTTP	8080	Non

3.2 Variables KvBus

Variable	Description	Défaut
KVBUS_MODE	Mode (in_memory/redis)	in_memory
REDIS_HOST	Hôte Redis	localhost
REDIS_PORT	Port Redis	6379
REDIS_PASSWORD	Mot de passe Redis	–
REDIS_DATABASE	Database Redis	0
REDIS_PREFIX	Préfixe des clés	socle

3.3 Variables Supervisor et Dashboard

Variable	Description	Défaut
SUPERVISOR_HEARTBEAT_MS	Intervalle heartbeat attendu	10000 (10s)
SUPERVISOR_UNHEALTHY_THRESHOLD	Heartbeats manqués avant UNHEALTHY	3
SUPERVISOR_CHECK_INTERVAL_MS	Fréquence de vérification	5000 (5s)
SUPERVISOR_STALE_TIMEOUT_MS	Timeout avant STALE	60000 (1min)
STATUS_DASHBOARD_ENABLED	Activer le dashboard	true
STATUS_DASHBOARD_PORT	Port du dashboard	9374
STATUS_DASHBOARD_REFRESH	Rafraîchissement (secondes)	5

3.4 Variables V4

Variable	Description	Défaut
TECHDB_ENABLED	Activer H2 TechDB	true
TECHDB_PATH	Chemin fichier H2	./data/socle-techdb
H2_CONSOLE_ENABLED	Console H2 web	false
LOG_FORWARDER_ENABLED	Activer LogForwarder	false
LOG_TRANSPORT_MODE	Mode transport logs	http
AUTH_ENABLED	Activer auth JWT	false
WORKER_REGISTRY_ENABLED	Activer registry	false

4. Classe SocleConfiguration

package eu.lmvi.socle.config;

@Configuration
@ConfigurationProperties(prefix = "socle")
public class SocleConfiguration {

    // === Identification ===
    private String app_name = "socle-v4";
    private String env_name = "DEV";
    private String exec_id;
    private String region = "local";
    private String version = "4.0.0";

    // === HTTP ===
    private HttpConfig http = new HttpConfig();

    // === KvBus ===
    private KvBusConfig kvbus = new KvBusConfig();

    // === Supervisor ===
    private SupervisorConfig supervisor = new SupervisorConfig();

    // === TechDB (V4) ===
    private TechDbConfig techdb = new TechDbConfig();

    // === Logging (V4) ===
    private LoggingConfig logging = new LoggingConfig();

    // === Auth (V4) ===
    private AuthConfig auth = new AuthConfig();

    // === Worker Registry (V4) ===
    private WorkerRegistryConfig workerRegistry = new WorkerRegistryConfig();

    // Getters / Setters...

    @PostConstruct
    public void init() {
        if (exec_id == null || exec_id.isEmpty()) {
            exec_id = app_name + "-" + UUID.randomUUID().toString().substring(0, 8);
        }
    }
}

4.1 Sous-configurations

public static class HttpConfig {
    private boolean enabled = true;
    private int port = 8080;
    private String contextPath = "/";
}

public static class KvBusConfig {
    private String mode = "in_memory";
    private RedisConfig redis = new RedisConfig();
}

public static class TechDbConfig {
    private boolean enabled = true;
    private String url = "jdbc:h2:file:./data/socle-techdb";
    private String username = "socle";
    private String password = "socle";
    private ConsoleConfig console = new ConsoleConfig();
}

public static class LoggingConfig {
    private ForwarderConfig forwarder = new ForwarderConfig();
}

public static class AuthConfig {
    private boolean enabled = false;
    private String serverUrl;
    private String sourceName;
    private String apiKey;
}

public static class WorkerRegistryConfig {
    private boolean enabled = false;
    private String serverUrl;
    private long heartbeatIntervalMs = 30000;
}

5. Accès à la configuration

5.1 Injection

@Service
public class MonService {

    @Autowired
    private SocleConfiguration config;

    public void doSomething() {
        String appName = config.getApp_name();
        String region = config.getRegion();
        boolean techDbEnabled = config.getTechdb().isEnabled();
    }
}

5.2 Dans un Worker

public class MonWorker implements Worker {

    private final SocleConfiguration config;

    public MonWorker(SocleConfiguration config) {
        this.config = config;
    }

    @Override
    public void doWork() {
        log.info("Running in region: {}", config.getRegion());
    }
}

6. Profils Spring

6.1 Activation

# Via variable d'environnement
export SPRING_PROFILES_ACTIVE=prod

# Via ligne de commande
java -jar app.jar --spring.profiles.active=prod

6.2 Fichiers par profil

src/main/resources/
├── application.yml           # Configuration de base
├── application-dev.yml       # Overrides DEV
├── application-staging.yml   # Overrides STAGING
└── application-prod.yml      # Overrides PROD

6.3 Exemple application-prod.yml

socle:
  env_name: PROD
  techdb:
    console:
      enabled: false
  logging:
    forwarder:
      enabled: true
  auth:
    enabled: true
  worker-registry:
    enabled: true

logging:
  config: classpath:log4j2-prod.xml

7. Configuration Docker

7.1 Dockerfile

FROM eclipse-temurin:21-jre

WORKDIR /app

COPY target/socle-v004-4.0.0.jar app.jar

# Variables par défaut (peuvent être overridées)
ENV APP_NAME=socle-v4
ENV ENV_NAME=PROD
ENV HTTP_PORT=8080
ENV TECHDB_PATH=/app/data/techdb

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "app.jar"]

7.2 docker-compose.yml

version: '3.8'

services:
  socle-app:
    image: socle-v4:latest
    environment:
      - APP_NAME=my-service
      - ENV_NAME=PROD
      - REGION=MTQ
      - KVBUS_MODE=redis
      - REDIS_HOST=redis
      - LOG_FORWARDER_ENABLED=true
      - LOG_HUB_URL=http://loghub:8080/api/ingest-logs
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

8. Configuration Kubernetes

8.1 ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: socle-config
data:
  APP_NAME: "my-service"
  ENV_NAME: "PROD"
  REGION: "MTQ"
  KVBUS_MODE: "redis"
  LOG_FORWARDER_ENABLED: "true"

8.2 Secret

apiVersion: v1
kind: Secret
metadata:
  name: socle-secrets
type: Opaque
stringData:
  REDIS_PASSWORD: "secret-password"
  API_KEY: "my-api-key"
  TECHDB_PASSWORD: "techdb-password"

8.3 Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: socle-app
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: socle
          image: socle-v4:latest
          envFrom:
            - configMapRef:
                name: socle-config
            - secretRef:
                name: socle-secrets
          ports:
            - containerPort: 8080

9. Validation de configuration

9.1 Validation au démarrage

@Component
public class ConfigurationValidator implements ApplicationListener<ApplicationReadyEvent> {

    @Autowired
    private SocleConfiguration config;

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        validateRequired();
        validateConsistency();
    }

    private void validateRequired() {
        if (config.getApp_name() == null || config.getApp_name().isEmpty()) {
            throw new IllegalStateException("APP_NAME is required");
        }
    }

    private void validateConsistency() {
        if (config.getAuth().isEnabled() && config.getAuth().getApiKey() == null) {
            throw new IllegalStateException("API_KEY required when AUTH_ENABLED=true");
        }
    }
}

9.2 Endpoint de configuration

GET /admin/config

Retourne la configuration actuelle (sans les secrets).

10. Bonnes pratiques

DO

• Utiliser les variables d’environnement pour les valeurs spécifiques à l’environnement
• Définir des valeurs par défaut sensées
• Utiliser des profils Spring pour les environnements
• Valider la configuration au démarrage
• Ne jamais committer de secrets

DON’T

• Ne pas hardcoder de valeurs dans le code
• Ne pas mettre de mots de passe dans application.yml
• Ne pas utiliser de valeurs par défaut dangereuses en prod

11. Références

• 02-ARCHITECTURE
• 03-QUICKSTART
• 08-SUPERVISOR – Supervision et heartbeats
• 21-H2-TECHDB
• 27-STATUS-DASHBOARD – Dashboard supervision
• GUIDE-METHODOLOGIQUE – Bonnes pratiques
• Spring Boot Configuration

31 – Communication gRPC Inter-Socles

Vue d’ensemble

Le module gRPC permet aux instances Socle V4 de communiquer entre elles via streaming bidirectionnel. Il offre :

• Sessions : Gestion de sessions multi-participants avec TTL
• Streaming bidirectionnel : Communication temps reel entre Socles
• Pipeline de traitement : Transformation des messages via Janino et JDM
• Fan-out : Routage broadcast ou cible vers les participants
• Pool de connexions : Connexions persistantes vers les peers

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Socle A                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ SessionMgr  │  │  Pipeline   │  │    GrpcServerWorker     │  │
│  │             │  │  Executor   │  │    (port 9400)          │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│         │               │                      │                 │
│         └───────────────┼──────────────────────┘                 │
│                         │                                        │
│              ┌──────────┴──────────┐                            │
│              │   gRPC Services     │                            │
│              │  - SocleComm        │                            │
│              │  - SessionService   │                            │
│              │  - DiscoveryService │                            │
│              └──────────┬──────────┘                            │
└─────────────────────────┼───────────────────────────────────────┘
                          │ gRPC/HTTP2
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Socle B                                  │
│              ┌──────────────────────┐                           │
│              │  PeerConnectionPool  │                           │
│              └──────────────────────┘                           │
└─────────────────────────────────────────────────────────────────┘

Configuration

application.yml

socle:
  grpc:
    # Activation du module
    enabled: ${GRPC_ENABLED:false}

    # Port du serveur gRPC
    port: ${GRPC_PORT:9400}

    # Identification du Socle
    socle-id: ${SOCLE_ID:${socle.app_name}}
    socle-version: ${socle.version}

    # Limites serveur
    max-inbound-message-size: ${GRPC_MAX_MESSAGE_SIZE:4194304}  # 4MB
    max-concurrent-calls-per-connection: ${GRPC_MAX_CONCURRENT_CALLS:100}

    # Sessions
    session:
      ttl-seconds: ${GRPC_SESSION_TTL:1800}           # 30 min
      max-participants: ${GRPC_MAX_PARTICIPANTS:100}
      persist-to-tech-db: ${GRPC_PERSIST_SESSIONS:true}
      cache-in-redis: ${GRPC_CACHE_REDIS:true}

    # Pipeline de traitement
    pipeline:
      enabled: ${GRPC_PIPELINE_ENABLED:true}
      config-cache-ttl-seconds: ${GRPC_PIPELINE_CACHE_TTL:300}

    # Connexions peer
    peer:
      max-channels-per-peer: ${GRPC_PEER_MAX_CHANNELS:4}
      connection-timeout-ms: ${GRPC_PEER_CONNECT_TIMEOUT:5000}
      idle-timeout-seconds: ${GRPC_PEER_IDLE_TIMEOUT:300}
      keep-alive-enabled: ${GRPC_PEER_KEEPALIVE:true}
      keep-alive-time-seconds: ${GRPC_PEER_KEEPALIVE_TIME:30}
      keep-alive-timeout-seconds: ${GRPC_PEER_KEEPALIVE_TIMEOUT:10}

Variables d’environnement

Variable	Default	Description
GRPC_ENABLED	false	Active le module gRPC
GRPC_PORT	9400	Port du serveur gRPC
SOCLE_ID	${app_name}	Identifiant unique du Socle
GRPC_SESSION_TTL	1800	TTL des sessions en secondes
GRPC_MAX_PARTICIPANTS	100	Max participants par session
GRPC_PIPELINE_ENABLED	true	Active le pipeline de traitement

Services gRPC

DiscoveryService

Service de decouverte et health check.

service DiscoveryService {
    rpc GetCapabilities(CapabilitiesRequest) returns (CapabilitiesResponse);
    rpc Ping(PingRequest) returns (PingResponse);
}

Test avec grpcurl :

# Ping
grpcurl -plaintext localhost:9400 socle.DiscoveryService/Ping

# Capabilities
grpcurl -plaintext localhost:9400 socle.DiscoveryService/GetCapabilities

SessionService

Gestion du cycle de vie des sessions.

service SessionService {
    rpc CreateSession(CreateSessionRequest) returns (SessionInfo);
    rpc JoinSession(JoinSessionRequest) returns (JoinSessionResponse);
    rpc LeaveSession(LeaveSessionRequest) returns (LeaveSessionResponse);
    rpc GetSession(GetSessionRequest) returns (SessionInfo);
    rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
}

Exemples :

# Creer une session
grpcurl -plaintext -d '{
  "session_type": "chat",
  "owner_id": "user1",
  "ttl_seconds": 3600
}' localhost:9400 socle.SessionService/CreateSession

# Joindre une session
grpcurl -plaintext -d '{
  "session_id": "uuid-de-la-session",
  "participant_id": "user2",
  "display_name": "User 2"
}' localhost:9400 socle.SessionService/JoinSession

# Obtenir info session
grpcurl -plaintext -d '{
  "session_id": "uuid-de-la-session"
}' localhost:9400 socle.SessionService/GetSession

SocleComm

Streaming bidirectionnel pour l’echange de messages.

service SocleComm {
    rpc Exchange(stream SessionMessage) returns (stream SessionMessage);
}

Format des messages :

message SessionMessage {
    string session_id = 1;
    string sender_id = 2;
    MessageKind kind = 3;        // JOIN, LEAVE, DATA, REQUEST, RESPONSE, etc.
    repeated string target_ids = 4;  // Vide = broadcast
    string correlation_id = 5;
    int64 timestamp = 6;
    string payload = 7;          // JSON
    map<string, string> headers = 8;
}

Sessions

Cycle de vie

CREATE ──► ACTIVE ──► CLOSING ──► CLOSED
              │
              └──► EXPIRED (TTL depasse)

Stockage

Les sessions sont stockees dans :

1. Cache memoire : Acces rapide, stream observers
2. Redis (si KvBus en mode redis) : Partage entre instances
3. TechDB : Audit et persistance

Tables TechDB

-- Sessions (audit)
CREATE TABLE grpc_sessions (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    session_id VARCHAR(36) NOT NULL UNIQUE,
    session_type VARCHAR(100) NOT NULL,
    owner_id VARCHAR(100) NOT NULL,
    status VARCHAR(20) DEFAULT 'ACTIVE',
    datas CLOB
);

-- Configuration pipeline par type de session
CREATE TABLE grpc_pipeline_configs (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    session_type VARCHAR(100) NOT NULL UNIQUE,
    janino_pre VARCHAR(255),
    jdm_rules VARCHAR(255),
    janino_post VARCHAR(255),
    default_targets VARCHAR(50) DEFAULT 'broadcast',
    enabled BOOLEAN DEFAULT TRUE,
    datas CLOB
);

Pipeline de traitement

Le pipeline permet de transformer les messages et determiner leur routage.

Etapes

Message entrant
      │
      ▼
┌─────────────────┐
│  1. Janino PRE  │  Transformation du payload
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  2. JDM Rules   │  Determination des cibles (routing)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  3. Janino POST │  Transformation finale
└────────┬────────┘
         │
         ▼
    Routage
   /        \
Broadcast   Cible

Configuration du pipeline

Inserez dans grpc_pipeline_configs :

INSERT INTO grpc_pipeline_configs
(session_type, janino_pre, jdm_rules, janino_post, default_targets, enabled)
VALUES
('chat', NULL, 'chat_routing', NULL, 'broadcast', TRUE);

Exemple script Janino PRE

// repository/scripts/java/grpc/chat_filter.java
public class ChatFilter {
    public Object execute(Map<String, Object> context) {
        Map<String, Object> payload = (Map<String, Object>) context.get("payload");
        String senderId = (String) context.get("senderId");

        // Ajouter metadata
        payload.put("processed_at", System.currentTimeMillis());
        payload.put("sender", senderId);

        return payload;
    }
}

Exemple modele JDM pour routing

{
  "name": "chat_routing",
  "nodes": [
    {
      "id": "input",
      "type": "inputNode",
      "content": {
        "fields": [
          {"field": "payload.target", "type": "string"},
          {"field": "payload.type", "type": "string"}
        ]
      }
    },
    {
      "id": "decision",
      "type": "decisionTableNode",
      "content": {
        "hitPolicy": "first",
        "inputs": [
          {"field": "payload.type"}
        ],
        "outputs": [
          {"field": "targets", "type": "string"},
          {"field": "broadcast", "type": "boolean"}
        ],
        "rules": [
          {"_input": ["private"], "_output": ["${payload.target}", false]},
          {"_input": ["broadcast"], "_output": ["", true]},
          {"_input": ["*"], "_output": ["", true]}
        ]
      }
    }
  ]
}

Connexions Peer

Ajouter un peer programmatiquement

@Autowired
private PeerConnectionPool peerPool;

public void connectToPeer() {
    // Ajouter et connecter
    boolean connected = peerPool.addPeer("socle-b", "192.168.1.100", 9400);

    if (connected) {
        // Ouvrir un stream
        peerPool.openStream("socle-b", message -> {
            // Handler pour messages entrants
            System.out.println("Received: " + message.getPayload());
        });

        // Envoyer un message
        SessionMessage msg = SessionMessage.newBuilder()
            .setSessionId("...")
            .setSenderId("local-participant")
            .setKind(MessageKind.DATA)
            .setPayload("{\"text\":\"Hello\"}")
            .build();

        peerPool.sendToPeer("socle-b", msg);
    }
}

Broadcast vers tous les peers

SessionMessage msg = SessionMessage.newBuilder()
    .setSessionId(sessionId)
    .setSenderId(myId)
    .setKind(MessageKind.DATA)
    .setPayload(jsonPayload)
    .build();

int sent = peerPool.broadcast(msg, null);  // null = inclure tous

Worker gRPC

Priorites

Methode	Valeur	Description
getStartPriority()	800	Demarre apres Janino (25) et JDM (30)
getStopPriority()	10	S’arrete tot pour drain des connexions

Statistiques

@Autowired
private GrpcServerWorker grpcWorker;

Map<String, Object> stats = grpcWorker.getStats();
// {
//   "running": true,
//   "port": 9400,
//   "sessions": { "cached_sessions": 5, "active_streams": 12 },
//   "messaging": { "messages_received": 1234, "messages_sent": 5678 },
//   "peers": { "connected_peers": 2, "total_messages_sent": 100 }
// }

Types de sessions supportes

Type	Description
chat	Communication temps reel
sync	Synchronisation de donnees
broadcast	Diffusion un-vers-plusieurs
pipeline	Traitement en chaine
custom	Type personnalise

Securite

TLS (a venir)

Le support TLS sera ajoute dans une version future :

socle:
  grpc:
    tls:
      enabled: true
      cert-path: /path/to/server.crt
      key-path: /path/to/server.key
      ca-path: /path/to/ca.crt  # Pour mTLS

Authentification

L’authentification peut etre implementee via :

• Metadata gRPC (tokens dans headers)
• Intercepteurs personnalises
• Integration avec le module Auth existant

Monitoring

Metriques exposees

Les metriques sont disponibles via l’endpoint Prometheus /actuator/prometheus :

• grpc_sessions_active : Nombre de sessions actives
• grpc_messages_received_total : Total messages recus
• grpc_messages_sent_total : Total messages envoyes
• grpc_peers_connected : Nombre de peers connectes

Logs

[grpc_server] Started on port 9400
[grpc_session] Session created: abc-123 (type=chat, owner=user1)
[grpc_session] Participant joined: user2 -> abc-123 (total: 2)
[grpc_comm] Message received: session=abc-123, sender=user1, kind=DATA
[grpc_pipeline] Executed for session abc-123 (targets=broadcast)

Troubleshooting

Le serveur ne demarre pas

1. Verifiez que le port 9400 n’est pas utilise
2. Verifiez GRPC_ENABLED=true
3. Consultez les logs pour les erreurs d’initialisation

Sessions expirent trop vite

Augmentez le TTL :

socle:
  grpc:
    session:
      ttl-seconds: 7200  # 2 heures

Messages non delivres

1. Verifiez que le destinataire a un stream actif
2. Verifiez les logs du pipeline pour les erreurs
3. Verifiez la configuration du routing dans grpc_pipeline_configs

Erreurs de connexion peer

1. Verifiez la connectivite reseau
2. Verifiez que le peer a gRPC active
3. Augmentez le timeout de connexion :

socle:
  grpc:
    peer:
      connection-timeout-ms: 10000

Structure des fichiers

src/main/java/eu/lmvi/socle/grpc/
├── GrpcConfiguration.java        # Configuration Spring
├── GrpcServerWorker.java         # Worker principal
├── session/
│   ├── Session.java              # Record session
│   ├── Participant.java          # Record participant
│   ├── SessionStatus.java        # Enum ACTIVE/CLOSING/CLOSED/EXPIRED
│   ├── SessionManager.java       # Gestion sessions + streams
│   └── SessionRedisRepository.java  # Persistance Redis
├── pipeline/
│   ├── PipelineConfig.java       # Config pipeline
│   ├── PipelineResult.java       # Resultat pipeline
│   └── PipelineExecutor.java     # Execution Janino + JDM
├── peer/
│   ├── PeerConnection.java       # Connexion unique
│   └── PeerConnectionPool.java   # Pool avec reconnexion
└── service/
    ├── SocleCommService.java     # Streaming bidirectionnel
    ├── SessionServiceImpl.java   # CRUD sessions
    └── DiscoveryServiceImpl.java # Discovery + Ping

src/main/proto/
└── socle_comm.proto              # Definition Protocol Buffers

28 – Standard de Creation de Table H2

Version : 4.0.1 Date : 2026-01-13 Package : eu.lmvi.socle.techdb

Introduction

Ce document definit le standard de creation des tables dans la base technique H2 du Socle V004. Ce standard garantit la coherence, la tracabilite et la compatibilite PostgreSQL/H2.

Structure de Base

Toutes les tables TechDB doivent suivre cette structure:

Champ	Type	Description
x_id	BIGINT GENERATED BY DEFAULT AS IDENTITY	Identifiant technique auto-genere
x_dateCreated	TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP	Date creation
x_dateChanged	TIMESTAMP WITH TIME ZONE	Date modification (NULL a l’insert, MAJ par appli)
x_sub	VARCHAR(255)	Sujet/categorie
x_partition	VARCHAR(30)	Partition logique
x_comment	CLOB	Commentaires/historiques JSON texte
[champs metier]	–	Champs specifiques a la table
datas	CLOB	Donnees metier JSON texte (toujours en fin)

Regles

Identite

• Utiliser GENERATED BY DEFAULT AS IDENTITY, pas AUTO_INCREMENT (MySQL)
• Pas de sequence explicite
• La colonne x_id est toujours la cle primaire

-- Correct (SQL standard / H2 / PostgreSQL)
x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY

-- Incorrect (MySQL uniquement)
id BIGINT AUTO_INCREMENT PRIMARY KEY

Timestamps

• x_dateCreated: Toujours NOT NULL DEFAULT CURRENT_TIMESTAMP
• x_dateChanged: NULL a l’insertion, mis a jour par l’application
• Utiliser TIMESTAMP WITH TIME ZONE pour la compatibilite

x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
x_dateChanged TIMESTAMP WITH TIME ZONE,

Triggers

• Aucun trigger dans H2
• L’audit, l’historisation et la mise a jour de x_dateChanged sont geres par l’application

Cle Primaire

• Si une cle existante est presente (ex: worker_name), la conserver comme UNIQUE
• x_id reste la PK technique

x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
worker_name VARCHAR(255) NOT NULL UNIQUE,

Conventions de Nommage

Element	Convention	Exemple
Champs techniques	Prefixe x_	x_id, x_dateCreated
Cles etrangeres	id_<table_cible>	id_user, id_order
Champ id existant	Renommer en x_id
Donnees JSON	datas en derniere position

Permissions

• Droits geres au niveau utilisateur H2
• Proprietaire = utilisateur createur (socle par defaut)

Contraintes H2 vs PostgreSQL

PostgreSQL	H2
JSONB	CLOB
Triggers natifs	Logique applicative
Validation JSON DB	Validation applicative
SERIAL	GENERATED BY DEFAULT AS IDENTITY
Index GIN sur JSON	Non supporte

Exemple DDL Complet

CREATE TABLE IF NOT EXISTS techdb_example (
    -- Champs techniques (standard)
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,

    -- Champs metier specifiques
    example_key VARCHAR(255) NOT NULL UNIQUE,
    status VARCHAR(50) NOT NULL,
    counter INT DEFAULT 0,
    last_activity TIMESTAMP WITH TIME ZONE,

    -- Donnees JSON (toujours en dernier)
    datas CLOB
);

-- Index recommandes
CREATE INDEX IF NOT EXISTS idx_example_key ON techdb_example(example_key);
CREATE INDEX IF NOT EXISTS idx_example_status ON techdb_example(status);
CREATE INDEX IF NOT EXISTS idx_example_created ON techdb_example(x_dateCreated);

Tables TechDB du Socle

Le Socle V004 definit 5 tables techniques:

techdb_offsets

Stockage des offsets de consommation (Kafka, NATS, etc.)

CREATE TABLE IF NOT EXISTS techdb_offsets (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    offset_key VARCHAR(255) NOT NULL UNIQUE,
    topic VARCHAR(255) NOT NULL,
    partition_id INT DEFAULT 0,
    offset_value BIGINT NOT NULL,
    consumer_group VARCHAR(255),
    datas CLOB
);

techdb_worker_state

Etat persistant des Workers

CREATE TABLE IF NOT EXISTS techdb_worker_state (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    worker_name VARCHAR(255) NOT NULL UNIQUE,
    state VARCHAR(50) NOT NULL,
    last_run_at TIMESTAMP WITH TIME ZONE,
    next_run_at TIMESTAMP WITH TIME ZONE,
    error_count INT DEFAULT 0,
    last_error CLOB,
    datas CLOB
);

techdb_events

Evenements techniques

CREATE TABLE IF NOT EXISTS techdb_events (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    event_type VARCHAR(100) NOT NULL,
    source VARCHAR(255) NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    processed_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

techdb_log_buffer

Buffer de logs pour LogForwarder

CREATE TABLE IF NOT EXISTS techdb_log_buffer (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    log_level VARCHAR(20) NOT NULL,
    logger_name VARCHAR(255),
    message CLOB NOT NULL,
    thread_name VARCHAR(255),
    log_timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
    forwarded BOOLEAN DEFAULT FALSE,
    forwarded_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

techdb_kv

Stockage cle-valeur generique

CREATE TABLE IF NOT EXISTS techdb_kv (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    kv_key VARCHAR(512) NOT NULL UNIQUE,
    value_type VARCHAR(50) DEFAULT 'string',
    expires_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

Bonnes Pratiques

DO

• Toujours utiliser le format standard x_ pour les champs techniques
• Mettre datas en derniere colonne
• Creer des index sur les colonnes frequemment requetees
• Utiliser TIMESTAMP WITH TIME ZONE pour tous les timestamps
• Documenter le contenu JSON attendu dans datas

DON’T

• Ne pas utiliser AUTO_INCREMENT (syntaxe MySQL)
• Ne pas creer de triggers (gestion applicative)
• Ne pas stocker de BLOBs volumineux (utiliser stockage externe)
• Ne pas utiliser JSONB (non supporte par H2)
• Ne pas omettre les index sur les colonnes de recherche

Migration depuis l’ancien format

Si vous avez des tables existantes avec l’ancien format:

-- 1. Sauvegarder les donnees
CREATE TABLE techdb_events_backup AS SELECT * FROM techdb_events;

-- 2. Supprimer l'ancienne table
DROP TABLE techdb_events;

-- 3. Recreer avec le nouveau format
-- (voir DDL ci-dessus)

-- 4. Migrer les donnees
INSERT INTO techdb_events (event_type, source, processed, processed_at, datas)
SELECT event_type, source, processed, processed_at, payload
FROM techdb_events_backup;

-- 5. Supprimer la sauvegarde
DROP TABLE techdb_events_backup;

Voir aussi

• 21-H2-TECHDB.md – Documentation TechDB complete
• 05-WORKERS.md – Workers TechDB

H2 = dev/tests/outillage – Structure compatible PostgreSQL/H2

Socle V004 – Standard TechDB

23 – Client Authentification JWT (Nouveauté V4)

Version : 4.0.0 Date : 2025-12-09

1. Introduction

Le SocleAuthClient est un client d’authentification JWT intégré au Socle V4 pour communiquer avec les services centraux (LogHub, Registry, etc.).

Pattern d’authentification

┌─────────────────┐                    ┌─────────────────┐
│   Application   │                    │  Auth Server    │
│   Socle V4      │                    │  (central)      │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │  1. POST /auth/login                 │
         │     {sourceName, apiKey}             │
         │─────────────────────────────────────►│
         │                                      │
         │  2. {accessToken, refreshToken}      │
         │◄─────────────────────────────────────│
         │                                      │
         │  3. Requêtes avec Bearer token       │
         │  Authorization: Bearer <accessToken> │
         │─────────────────────────────────────►│ Services
         │                                      │
         │  4. POST /auth/refresh (auto)        │
         │     {refreshToken}                   │
         │─────────────────────────────────────►│
         │                                      │
         │  5. {accessToken (new)}              │
         │◄─────────────────────────────────────│

2. Configuration

2.1 application.yml

socle:
  auth:
    enabled: ${AUTH_ENABLED:false}
    server-url: ${AUTH_SERVER_URL:https://auth.lmvi.org}
    source-name: ${SOURCE_NAME:${socle.app_name}}
    api-key: ${API_KEY:}
    access-token-buffer-seconds: 60
    connect-timeout-ms: 10000
    read-timeout-ms: 30000

2.2 Variables d’environnement

Variable	Description	Défaut
AUTH_ENABLED	Activer l’authentification	false
AUTH_SERVER_URL	URL du serveur d’auth	–
SOURCE_NAME	Identifiant du client	${APP_NAME}
API_KEY	Clé API (secret)	–

3. Interface SocleAuthClient

package eu.lmvi.socle.client.auth;

/**
 * Client d'authentification Socle V4
 */
public interface SocleAuthClient {

    /**
     * Login initial avec API Key
     * @return Tokens d'accès et de refresh
     * @throws AuthenticationException si échec
     */
    AuthTokens login() throws AuthenticationException;

    /**
     * Refresh du token d'accès
     * @param refreshToken Token de refresh
     * @return Nouveaux tokens
     * @throws AuthenticationException si échec
     */
    AuthTokens refresh(String refreshToken) throws AuthenticationException;

    /**
     * Obtenir un token d'accès valide (avec refresh auto si nécessaire)
     * @return Token d'accès valide
     * @throws AuthenticationException si échec
     */
    String getValidAccessToken() throws AuthenticationException;

    /**
     * Vérifie si le client est authentifié
     * @return true si un token valide existe
     */
    boolean isAuthenticated();

    /**
     * Invalide les tokens courants
     */
    void logout();
}

4. DTOs

4.1 AuthTokens

package eu.lmvi.socle.client.auth;

public record AuthTokens(
    String accessToken,
    String refreshToken,
    Instant accessTokenExpiry,
    Instant refreshTokenExpiry
) {
    public boolean isAccessTokenExpired() {
        return Instant.now().isAfter(accessTokenExpiry);
    }

    public boolean isAccessTokenExpiringSoon(int bufferSeconds) {
        return Instant.now().plusSeconds(bufferSeconds).isAfter(accessTokenExpiry);
    }

    public boolean isRefreshTokenExpired() {
        return Instant.now().isAfter(refreshTokenExpiry);
    }
}

4.2 LoginRequest / LoginResponse

// Request
public record LoginRequest(
    String sourceName,
    String apiKey
) {}

// Response
public record LoginResponse(
    String accessToken,
    String refreshToken,
    int expiresIn,        // secondes
    int refreshExpiresIn  // secondes
) {}

5. Implémentation AuthTokenManager

package eu.lmvi.socle.client.auth;

@Component
@ConditionalOnProperty(name = "socle.auth.enabled", havingValue = "true")
public class AuthTokenManager implements SocleAuthClient {

    private static final Logger log = LoggerFactory.getLogger(AuthTokenManager.class);

    private final SocleConfiguration config;
    private final OkHttpClient httpClient;
    private final ObjectMapper objectMapper;

    private volatile AuthTokens currentTokens;
    private final ReentrantLock refreshLock = new ReentrantLock();

    public AuthTokenManager(SocleConfiguration config) {
        this.config = config;
        this.objectMapper = new ObjectMapper();
        this.objectMapper.registerModule(new JavaTimeModule());

        this.httpClient = new OkHttpClient.Builder()
            .connectTimeout(config.getAuthConnectTimeoutMs(), TimeUnit.MILLISECONDS)
            .readTimeout(config.getAuthReadTimeoutMs(), TimeUnit.MILLISECONDS)
            .build();
    }

    @Override
    public AuthTokens login() throws AuthenticationException {
        log.info("Login to auth server: {}", config.getAuthServerUrl());

        LoginRequest request = new LoginRequest(
            config.getSourceName(),
            config.getApiKey()
        );

        try {
            String json = objectMapper.writeValueAsString(request);

            Request httpRequest = new Request.Builder()
                .url(config.getAuthServerUrl() + "/api/v1/auth/login")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();

            try (Response response = httpClient.newCall(httpRequest).execute()) {
                if (!response.isSuccessful()) {
                    throw new AuthenticationException("Login failed: " + response.code());
                }

                LoginResponse loginResponse = objectMapper.readValue(
                    response.body().string(),
                    LoginResponse.class
                );

                currentTokens = new AuthTokens(
                    loginResponse.accessToken(),
                    loginResponse.refreshToken(),
                    Instant.now().plusSeconds(loginResponse.expiresIn()),
                    Instant.now().plusSeconds(loginResponse.refreshExpiresIn())
                );

                log.info("Login successful, token expires in {} seconds", loginResponse.expiresIn());
                return currentTokens;
            }
        } catch (IOException e) {
            throw new AuthenticationException("Login failed", e);
        }
    }

    @Override
    public AuthTokens refresh(String refreshToken) throws AuthenticationException {
        log.debug("Refreshing access token");

        RefreshRequest request = new RefreshRequest(refreshToken);

        try {
            String json = objectMapper.writeValueAsString(request);

            Request httpRequest = new Request.Builder()
                .url(config.getAuthServerUrl() + "/api/v1/auth/refresh")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();

            try (Response response = httpClient.newCall(httpRequest).execute()) {
                if (!response.isSuccessful()) {
                    // Refresh failed, need to re-login
                    log.warn("Refresh failed, attempting re-login");
                    return login();
                }

                RefreshResponse refreshResponse = objectMapper.readValue(
                    response.body().string(),
                    RefreshResponse.class
                );

                currentTokens = new AuthTokens(
                    refreshResponse.accessToken(),
                    currentTokens.refreshToken(),  // Keep same refresh token
                    Instant.now().plusSeconds(refreshResponse.expiresIn()),
                    currentTokens.refreshTokenExpiry()
                );

                log.debug("Token refreshed, new expiry in {} seconds", refreshResponse.expiresIn());
                return currentTokens;
            }
        } catch (IOException e) {
            throw new AuthenticationException("Refresh failed", e);
        }
    }

    @Override
    public String getValidAccessToken() throws AuthenticationException {
        // First time - login
        if (currentTokens == null) {
            login();
            return currentTokens.accessToken();
        }

        // Refresh token expired - need full re-login
        if (currentTokens.isRefreshTokenExpired()) {
            log.info("Refresh token expired, re-login required");
            login();
            return currentTokens.accessToken();
        }

        // Access token expiring soon - refresh
        int bufferSeconds = config.getAccessTokenBufferSeconds();
        if (currentTokens.isAccessTokenExpiringSoon(bufferSeconds)) {
            refreshLock.lock();
            try {
                // Double-check after acquiring lock
                if (currentTokens.isAccessTokenExpiringSoon(bufferSeconds)) {
                    refresh(currentTokens.refreshToken());
                }
            } finally {
                refreshLock.unlock();
            }
        }

        return currentTokens.accessToken();
    }

    @Override
    public boolean isAuthenticated() {
        return currentTokens != null && !currentTokens.isAccessTokenExpired();
    }

    @Override
    public void logout() {
        currentTokens = null;
        log.info("Logged out");
    }
}

6. Utilisation

6.1 Injection

@Service
public class MonService {

    @Autowired(required = false)
    private SocleAuthClient authClient;

    public void callSecuredApi() throws Exception {
        if (authClient == null || !authClient.isAuthenticated()) {
            throw new IllegalStateException("Auth not configured");
        }

        String token = authClient.getValidAccessToken();

        // Utiliser le token
        Request request = new Request.Builder()
            .url("https://api.mycompany.com/secured")
            .header("Authorization", "Bearer " + token)
            .build();

        // ...
    }
}

6.2 Intégration avec LogForwarder

// Dans HttpLogTransport
public class HttpLogTransport implements LogTransport {

    private final SocleAuthClient authClient;

    @Override
    public void send(List<LogEntry> entries) throws Exception {
        String token = authClient.getValidAccessToken();

        Request request = new Request.Builder()
            .url(logHubUrl)
            .header("Authorization", "Bearer " + token)
            .post(RequestBody.create(toJson(entries), JSON))
            .build();

        // ...
    }
}

6.3 Intégration avec MOP

// Dans MainOrchestratorProcess.start()
if (authClient != null && config.isAuthEnabled()) {
    log.info("[step:auth] Login auprès du serveur d'auth");
    try {
        authClient.login();
    } catch (AuthenticationException e) {
        log.error("Auth failed, continuing without auth", e);
    }
}

7. Gestion des erreurs

7.1 AuthenticationException

public class AuthenticationException extends Exception {
    public AuthenticationException(String message) {
        super(message);
    }

    public AuthenticationException(String message, Throwable cause) {
        super(message, cause);
    }
}

7.2 Retry automatique

Le AuthTokenManager gère automatiquement :

• Le refresh avant expiration
• Le re-login si le refresh échoue
• Le re-login si le refresh token expire

7.3 Fallback sans auth

if (authClient == null) {
    log.warn("Auth not configured, proceeding without authentication");
    // Continuer sans auth (pour dev local)
}

8. Sécurité

8.1 Stockage de l’API Key

# NE PAS mettre dans le code
# Utiliser des variables d'environnement
export API_KEY="xxx-secret-key"

# Ou un gestionnaire de secrets
# Kubernetes Secret, AWS Secrets Manager, etc.

8.2 Tokens en mémoire

Les tokens sont stockés en mémoire uniquement :

• Jamais persistés sur disque
• Invalidés au restart
• Thread-safe

8.3 HTTPS obligatoire

socle:
  auth:
    server-url: https://auth.mycompany.com  # HTTPS obligatoire

9. Monitoring

9.1 Métriques

// Exposées via /metrics
socle_auth_login_total          # Nombre de logins
socle_auth_login_errors_total   # Erreurs de login
socle_auth_refresh_total        # Nombre de refresh
socle_auth_token_expiry_seconds # Temps avant expiration

9.2 Logs

INFO  - Login to auth server: https://auth.lmvi.org
INFO  - Login successful, token expires in 900 seconds
DEBUG - Refreshing access token
DEBUG - Token refreshed, new expiry in 900 seconds
WARN  - Refresh failed, attempting re-login

10. Troubleshooting

Connection refused

AuthenticationException: Login failed: Connection refused

Vérifier :

• AUTH_SERVER_URL est correct
• Le serveur d’auth est accessible
• Les ports sont ouverts

Invalid API Key

AuthenticationException: Login failed: 401

Vérifier :

• API_KEY est correct
• SOURCE_NAME est enregistré côté serveur

Token expired

Si les tokens expirent trop vite :

• Vérifier l’horloge système (NTP)
• Augmenter access-token-buffer-seconds

11. Références

• RFC 7519 – JWT
• OAuth 2.0
• 10-SECURITY

28 – Standard de Creation de Table H2

Version : 4.0.1 Date : 2026-01-13 Package : eu.lmvi.socle.techdb

Introduction

Ce document definit le standard de creation des tables dans la base technique H2 du Socle V004. Ce standard garantit la coherence, la tracabilite et la compatibilite PostgreSQL/H2.

Structure de Base

Toutes les tables TechDB doivent suivre cette structure:

Champ	Type	Description
x_id	BIGINT GENERATED BY DEFAULT AS IDENTITY	Identifiant technique auto-genere
x_dateCreated	TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP	Date creation
x_dateChanged	TIMESTAMP WITH TIME ZONE	Date modification (NULL a l’insert, MAJ par appli)
x_sub	VARCHAR(255)	Sujet/categorie
x_partition	VARCHAR(30)	Partition logique
x_comment	CLOB	Commentaires/historiques JSON texte
[champs metier]	–	Champs specifiques a la table
datas	CLOB	Donnees metier JSON texte (toujours en fin)

Regles

Identite

• Utiliser GENERATED BY DEFAULT AS IDENTITY, pas AUTO_INCREMENT (MySQL)
• Pas de sequence explicite
• La colonne x_id est toujours la cle primaire

-- Correct (SQL standard / H2 / PostgreSQL)
x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY

-- Incorrect (MySQL uniquement)
id BIGINT AUTO_INCREMENT PRIMARY KEY

Timestamps

• x_dateCreated: Toujours NOT NULL DEFAULT CURRENT_TIMESTAMP
• x_dateChanged: NULL a l’insertion, mis a jour par l’application
• Utiliser TIMESTAMP WITH TIME ZONE pour la compatibilite

x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
x_dateChanged TIMESTAMP WITH TIME ZONE,

Triggers

• Aucun trigger dans H2
• L’audit, l’historisation et la mise a jour de x_dateChanged sont geres par l’application

Cle Primaire

• Si une cle existante est presente (ex: worker_name), la conserver comme UNIQUE
• x_id reste la PK technique

x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
worker_name VARCHAR(255) NOT NULL UNIQUE,

Conventions de Nommage

Element	Convention	Exemple
Champs techniques	Prefixe x_	x_id, x_dateCreated
Cles etrangeres	id_<table_cible>	id_user, id_order
Champ id existant	Renommer en x_id
Donnees JSON	datas en derniere position

Permissions

• Droits geres au niveau utilisateur H2
• Proprietaire = utilisateur createur (socle par defaut)

Contraintes H2 vs PostgreSQL

PostgreSQL	H2
JSONB	CLOB
Triggers natifs	Logique applicative
Validation JSON DB	Validation applicative
SERIAL	GENERATED BY DEFAULT AS IDENTITY
Index GIN sur JSON	Non supporte

Exemple DDL Complet

CREATE TABLE IF NOT EXISTS techdb_example (
    -- Champs techniques (standard)
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,

    -- Champs metier specifiques
    example_key VARCHAR(255) NOT NULL UNIQUE,
    status VARCHAR(50) NOT NULL,
    counter INT DEFAULT 0,
    last_activity TIMESTAMP WITH TIME ZONE,

    -- Donnees JSON (toujours en dernier)
    datas CLOB
);

-- Index recommandes
CREATE INDEX IF NOT EXISTS idx_example_key ON techdb_example(example_key);
CREATE INDEX IF NOT EXISTS idx_example_status ON techdb_example(status);
CREATE INDEX IF NOT EXISTS idx_example_created ON techdb_example(x_dateCreated);

Tables TechDB du Socle

Le Socle V004 definit 5 tables techniques:

techdb_offsets

Stockage des offsets de consommation (Kafka, NATS, etc.)

CREATE TABLE IF NOT EXISTS techdb_offsets (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    offset_key VARCHAR(255) NOT NULL UNIQUE,
    topic VARCHAR(255) NOT NULL,
    partition_id INT DEFAULT 0,
    offset_value BIGINT NOT NULL,
    consumer_group VARCHAR(255),
    datas CLOB
);

techdb_worker_state

Etat persistant des Workers

CREATE TABLE IF NOT EXISTS techdb_worker_state (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    worker_name VARCHAR(255) NOT NULL UNIQUE,
    state VARCHAR(50) NOT NULL,
    last_run_at TIMESTAMP WITH TIME ZONE,
    next_run_at TIMESTAMP WITH TIME ZONE,
    error_count INT DEFAULT 0,
    last_error CLOB,
    datas CLOB
);

techdb_events

Evenements techniques

CREATE TABLE IF NOT EXISTS techdb_events (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    event_type VARCHAR(100) NOT NULL,
    source VARCHAR(255) NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    processed_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

techdb_log_buffer

Buffer de logs pour LogForwarder

CREATE TABLE IF NOT EXISTS techdb_log_buffer (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    log_level VARCHAR(20) NOT NULL,
    logger_name VARCHAR(255),
    message CLOB NOT NULL,
    thread_name VARCHAR(255),
    log_timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
    forwarded BOOLEAN DEFAULT FALSE,
    forwarded_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

techdb_kv

Stockage cle-valeur generique

CREATE TABLE IF NOT EXISTS techdb_kv (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    kv_key VARCHAR(512) NOT NULL UNIQUE,
    value_type VARCHAR(50) DEFAULT 'string',
    expires_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

Bonnes Pratiques

DO

• Toujours utiliser le format standard x_ pour les champs techniques
• Mettre datas en derniere colonne
• Creer des index sur les colonnes frequemment requetees
• Utiliser TIMESTAMP WITH TIME ZONE pour tous les timestamps
• Documenter le contenu JSON attendu dans datas

DON’T

• Ne pas utiliser AUTO_INCREMENT (syntaxe MySQL)
• Ne pas creer de triggers (gestion applicative)
• Ne pas stocker de BLOBs volumineux (utiliser stockage externe)
• Ne pas utiliser JSONB (non supporte par H2)
• Ne pas omettre les index sur les colonnes de recherche

Migration depuis l’ancien format

Si vous avez des tables existantes avec l’ancien format:

-- 1. Sauvegarder les donnees
CREATE TABLE techdb_events_backup AS SELECT * FROM techdb_events;

-- 2. Supprimer l'ancienne table
DROP TABLE techdb_events;

-- 3. Recreer avec le nouveau format
-- (voir DDL ci-dessus)

-- 4. Migrer les donnees
INSERT INTO techdb_events (event_type, source, processed, processed_at, datas)
SELECT event_type, source, processed, processed_at, payload
FROM techdb_events_backup;

-- 5. Supprimer la sauvegarde
DROP TABLE techdb_events_backup;

Voir aussi

• 21-H2-TECHDB.md – Documentation TechDB complete
• 05-WORKERS.md – Workers TechDB

H2 = dev/tests/outillage – Structure compatible PostgreSQL/H2

Socle V004 – Standard TechDB

23 – Client Authentification JWT (Nouveauté V4)

Version : 4.0.0 Date : 2025-12-09

1. Introduction

Le SocleAuthClient est un client d’authentification JWT intégré au Socle V4 pour communiquer avec les services centraux (LogHub, Registry, etc.).

Pattern d’authentification

┌─────────────────┐                    ┌─────────────────┐
│   Application   │                    │  Auth Server    │
│   Socle V4      │                    │  (central)      │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │  1. POST /auth/login                 │
         │     {sourceName, apiKey}             │
         │─────────────────────────────────────►│
         │                                      │
         │  2. {accessToken, refreshToken}      │
         │◄─────────────────────────────────────│
         │                                      │
         │  3. Requêtes avec Bearer token       │
         │  Authorization: Bearer <accessToken> │
         │─────────────────────────────────────►│ Services
         │                                      │
         │  4. POST /auth/refresh (auto)        │
         │     {refreshToken}                   │
         │─────────────────────────────────────►│
         │                                      │
         │  5. {accessToken (new)}              │
         │◄─────────────────────────────────────│

2. Configuration

2.1 application.yml

socle:
  auth:
    enabled: ${AUTH_ENABLED:false}
    server-url: ${AUTH_SERVER_URL:https://auth.lmvi.org}
    source-name: ${SOURCE_NAME:${socle.app_name}}
    api-key: ${API_KEY:}
    access-token-buffer-seconds: 60
    connect-timeout-ms: 10000
    read-timeout-ms: 30000

2.2 Variables d’environnement

Variable	Description	Défaut
AUTH_ENABLED	Activer l’authentification	false
AUTH_SERVER_URL	URL du serveur d’auth	–
SOURCE_NAME	Identifiant du client	${APP_NAME}
API_KEY	Clé API (secret)	–

3. Interface SocleAuthClient

package eu.lmvi.socle.client.auth;

/**
 * Client d'authentification Socle V4
 */
public interface SocleAuthClient {

    /**
     * Login initial avec API Key
     * @return Tokens d'accès et de refresh
     * @throws AuthenticationException si échec
     */
    AuthTokens login() throws AuthenticationException;

    /**
     * Refresh du token d'accès
     * @param refreshToken Token de refresh
     * @return Nouveaux tokens
     * @throws AuthenticationException si échec
     */
    AuthTokens refresh(String refreshToken) throws AuthenticationException;

    /**
     * Obtenir un token d'accès valide (avec refresh auto si nécessaire)
     * @return Token d'accès valide
     * @throws AuthenticationException si échec
     */
    String getValidAccessToken() throws AuthenticationException;

    /**
     * Vérifie si le client est authentifié
     * @return true si un token valide existe
     */
    boolean isAuthenticated();

    /**
     * Invalide les tokens courants
     */
    void logout();
}

4. DTOs

4.1 AuthTokens

package eu.lmvi.socle.client.auth;

public record AuthTokens(
    String accessToken,
    String refreshToken,
    Instant accessTokenExpiry,
    Instant refreshTokenExpiry
) {
    public boolean isAccessTokenExpired() {
        return Instant.now().isAfter(accessTokenExpiry);
    }

    public boolean isAccessTokenExpiringSoon(int bufferSeconds) {
        return Instant.now().plusSeconds(bufferSeconds).isAfter(accessTokenExpiry);
    }

    public boolean isRefreshTokenExpired() {
        return Instant.now().isAfter(refreshTokenExpiry);
    }
}

4.2 LoginRequest / LoginResponse

// Request
public record LoginRequest(
    String sourceName,
    String apiKey
) {}

// Response
public record LoginResponse(
    String accessToken,
    String refreshToken,
    int expiresIn,        // secondes
    int refreshExpiresIn  // secondes
) {}

5. Implémentation AuthTokenManager

package eu.lmvi.socle.client.auth;

@Component
@ConditionalOnProperty(name = "socle.auth.enabled", havingValue = "true")
public class AuthTokenManager implements SocleAuthClient {

    private static final Logger log = LoggerFactory.getLogger(AuthTokenManager.class);

    private final SocleConfiguration config;
    private final OkHttpClient httpClient;
    private final ObjectMapper objectMapper;

    private volatile AuthTokens currentTokens;
    private final ReentrantLock refreshLock = new ReentrantLock();

    public AuthTokenManager(SocleConfiguration config) {
        this.config = config;
        this.objectMapper = new ObjectMapper();
        this.objectMapper.registerModule(new JavaTimeModule());

        this.httpClient = new OkHttpClient.Builder()
            .connectTimeout(config.getAuthConnectTimeoutMs(), TimeUnit.MILLISECONDS)
            .readTimeout(config.getAuthReadTimeoutMs(), TimeUnit.MILLISECONDS)
            .build();
    }

    @Override
    public AuthTokens login() throws AuthenticationException {
        log.info("Login to auth server: {}", config.getAuthServerUrl());

        LoginRequest request = new LoginRequest(
            config.getSourceName(),
            config.getApiKey()
        );

        try {
            String json = objectMapper.writeValueAsString(request);

            Request httpRequest = new Request.Builder()
                .url(config.getAuthServerUrl() + "/api/v1/auth/login")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();

            try (Response response = httpClient.newCall(httpRequest).execute()) {
                if (!response.isSuccessful()) {
                    throw new AuthenticationException("Login failed: " + response.code());
                }

                LoginResponse loginResponse = objectMapper.readValue(
                    response.body().string(),
                    LoginResponse.class
                );

                currentTokens = new AuthTokens(
                    loginResponse.accessToken(),
                    loginResponse.refreshToken(),
                    Instant.now().plusSeconds(loginResponse.expiresIn()),
                    Instant.now().plusSeconds(loginResponse.refreshExpiresIn())
                );

                log.info("Login successful, token expires in {} seconds", loginResponse.expiresIn());
                return currentTokens;
            }
        } catch (IOException e) {
            throw new AuthenticationException("Login failed", e);
        }
    }

    @Override
    public AuthTokens refresh(String refreshToken) throws AuthenticationException {
        log.debug("Refreshing access token");

        RefreshRequest request = new RefreshRequest(refreshToken);

        try {
            String json = objectMapper.writeValueAsString(request);

            Request httpRequest = new Request.Builder()
                .url(config.getAuthServerUrl() + "/api/v1/auth/refresh")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();

            try (Response response = httpClient.newCall(httpRequest).execute()) {
                if (!response.isSuccessful()) {
                    // Refresh failed, need to re-login
                    log.warn("Refresh failed, attempting re-login");
                    return login();
                }

                RefreshResponse refreshResponse = objectMapper.readValue(
                    response.body().string(),
                    RefreshResponse.class
                );

                currentTokens = new AuthTokens(
                    refreshResponse.accessToken(),
                    currentTokens.refreshToken(),  // Keep same refresh token
                    Instant.now().plusSeconds(refreshResponse.expiresIn()),
                    currentTokens.refreshTokenExpiry()
                );

                log.debug("Token refreshed, new expiry in {} seconds", refreshResponse.expiresIn());
                return currentTokens;
            }
        } catch (IOException e) {
            throw new AuthenticationException("Refresh failed", e);
        }
    }

    @Override
    public String getValidAccessToken() throws AuthenticationException {
        // First time - login
        if (currentTokens == null) {
            login();
            return currentTokens.accessToken();
        }

        // Refresh token expired - need full re-login
        if (currentTokens.isRefreshTokenExpired()) {
            log.info("Refresh token expired, re-login required");
            login();
            return currentTokens.accessToken();
        }

        // Access token expiring soon - refresh
        int bufferSeconds = config.getAccessTokenBufferSeconds();
        if (currentTokens.isAccessTokenExpiringSoon(bufferSeconds)) {
            refreshLock.lock();
            try {
                // Double-check after acquiring lock
                if (currentTokens.isAccessTokenExpiringSoon(bufferSeconds)) {
                    refresh(currentTokens.refreshToken());
                }
            } finally {
                refreshLock.unlock();
            }
        }

        return currentTokens.accessToken();
    }

    @Override
    public boolean isAuthenticated() {
        return currentTokens != null && !currentTokens.isAccessTokenExpired();
    }

    @Override
    public void logout() {
        currentTokens = null;
        log.info("Logged out");
    }
}

6. Utilisation

6.1 Injection

@Service
public class MonService {

    @Autowired(required = false)
    private SocleAuthClient authClient;

    public void callSecuredApi() throws Exception {
        if (authClient == null || !authClient.isAuthenticated()) {
            throw new IllegalStateException("Auth not configured");
        }

        String token = authClient.getValidAccessToken();

        // Utiliser le token
        Request request = new Request.Builder()
            .url("https://api.mycompany.com/secured")
            .header("Authorization", "Bearer " + token)
            .build();

        // ...
    }
}

6.2 Intégration avec LogForwarder

// Dans HttpLogTransport
public class HttpLogTransport implements LogTransport {

    private final SocleAuthClient authClient;

    @Override
    public void send(List<LogEntry> entries) throws Exception {
        String token = authClient.getValidAccessToken();

        Request request = new Request.Builder()
            .url(logHubUrl)
            .header("Authorization", "Bearer " + token)
            .post(RequestBody.create(toJson(entries), JSON))
            .build();

        // ...
    }
}

6.3 Intégration avec MOP

// Dans MainOrchestratorProcess.start()
if (authClient != null && config.isAuthEnabled()) {
    log.info("[step:auth] Login auprès du serveur d'auth");
    try {
        authClient.login();
    } catch (AuthenticationException e) {
        log.error("Auth failed, continuing without auth", e);
    }
}

7. Gestion des erreurs

7.1 AuthenticationException

public class AuthenticationException extends Exception {
    public AuthenticationException(String message) {
        super(message);
    }

    public AuthenticationException(String message, Throwable cause) {
        super(message, cause);
    }
}

7.2 Retry automatique

Le AuthTokenManager gère automatiquement :

• Le refresh avant expiration
• Le re-login si le refresh échoue
• Le re-login si le refresh token expire

7.3 Fallback sans auth

if (authClient == null) {
    log.warn("Auth not configured, proceeding without authentication");
    // Continuer sans auth (pour dev local)
}

8. Sécurité

8.1 Stockage de l’API Key

# NE PAS mettre dans le code
# Utiliser des variables d'environnement
export API_KEY="xxx-secret-key"

# Ou un gestionnaire de secrets
# Kubernetes Secret, AWS Secrets Manager, etc.

8.2 Tokens en mémoire

Les tokens sont stockés en mémoire uniquement :

• Jamais persistés sur disque
• Invalidés au restart
• Thread-safe

8.3 HTTPS obligatoire

socle:
  auth:
    server-url: https://auth.mycompany.com  # HTTPS obligatoire

9. Monitoring

9.1 Métriques

// Exposées via /metrics
socle_auth_login_total          # Nombre de logins
socle_auth_login_errors_total   # Erreurs de login
socle_auth_refresh_total        # Nombre de refresh
socle_auth_token_expiry_seconds # Temps avant expiration

9.2 Logs

INFO  - Login to auth server: https://auth.lmvi.org
INFO  - Login successful, token expires in 900 seconds
DEBUG - Refreshing access token
DEBUG - Token refreshed, new expiry in 900 seconds
WARN  - Refresh failed, attempting re-login

10. Troubleshooting

Connection refused

AuthenticationException: Login failed: Connection refused

Vérifier :

• AUTH_SERVER_URL est correct
• Le serveur d’auth est accessible
• Les ports sont ouverts

Invalid API Key

AuthenticationException: Login failed: 401

Vérifier :

• API_KEY est correct
• SOURCE_NAME est enregistré côté serveur

Token expired

Si les tokens expirent trop vite :

• Vérifier l’horloge système (NTP)
• Augmenter access-token-buffer-seconds

11. Références

• RFC 7519 – JWT
• OAuth 2.0
• 10-SECURITY

28 – Standard de Creation de Table H2

Version : 4.0.1 Date : 2026-01-13 Package : eu.lmvi.socle.techdb

Introduction

Ce document definit le standard de creation des tables dans la base technique H2 du Socle V004. Ce standard garantit la coherence, la tracabilite et la compatibilite PostgreSQL/H2.

Structure de Base

Toutes les tables TechDB doivent suivre cette structure:

Champ	Type	Description
x_id	BIGINT GENERATED BY DEFAULT AS IDENTITY	Identifiant technique auto-genere
x_dateCreated	TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP	Date creation
x_dateChanged	TIMESTAMP WITH TIME ZONE	Date modification (NULL a l’insert, MAJ par appli)
x_sub	VARCHAR(255)	Sujet/categorie
x_partition	VARCHAR(30)	Partition logique
x_comment	CLOB	Commentaires/historiques JSON texte
[champs metier]	–	Champs specifiques a la table
datas	CLOB	Donnees metier JSON texte (toujours en fin)

Regles

Identite

• Utiliser GENERATED BY DEFAULT AS IDENTITY, pas AUTO_INCREMENT (MySQL)
• Pas de sequence explicite
• La colonne x_id est toujours la cle primaire

-- Correct (SQL standard / H2 / PostgreSQL)
x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY

-- Incorrect (MySQL uniquement)
id BIGINT AUTO_INCREMENT PRIMARY KEY

Timestamps

• x_dateCreated: Toujours NOT NULL DEFAULT CURRENT_TIMESTAMP
• x_dateChanged: NULL a l’insertion, mis a jour par l’application
• Utiliser TIMESTAMP WITH TIME ZONE pour la compatibilite

x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
x_dateChanged TIMESTAMP WITH TIME ZONE,

Triggers

• Aucun trigger dans H2
• L’audit, l’historisation et la mise a jour de x_dateChanged sont geres par l’application

Cle Primaire

• Si une cle existante est presente (ex: worker_name), la conserver comme UNIQUE
• x_id reste la PK technique

x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
worker_name VARCHAR(255) NOT NULL UNIQUE,

Conventions de Nommage

Element	Convention	Exemple
Champs techniques	Prefixe x_	x_id, x_dateCreated
Cles etrangeres	id_<table_cible>	id_user, id_order
Champ id existant	Renommer en x_id
Donnees JSON	datas en derniere position

Permissions

• Droits geres au niveau utilisateur H2
• Proprietaire = utilisateur createur (socle par defaut)

Contraintes H2 vs PostgreSQL

PostgreSQL	H2
JSONB	CLOB
Triggers natifs	Logique applicative
Validation JSON DB	Validation applicative
SERIAL	GENERATED BY DEFAULT AS IDENTITY
Index GIN sur JSON	Non supporte

Exemple DDL Complet

CREATE TABLE IF NOT EXISTS techdb_example (
    -- Champs techniques (standard)
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,

    -- Champs metier specifiques
    example_key VARCHAR(255) NOT NULL UNIQUE,
    status VARCHAR(50) NOT NULL,
    counter INT DEFAULT 0,
    last_activity TIMESTAMP WITH TIME ZONE,

    -- Donnees JSON (toujours en dernier)
    datas CLOB
);

-- Index recommandes
CREATE INDEX IF NOT EXISTS idx_example_key ON techdb_example(example_key);
CREATE INDEX IF NOT EXISTS idx_example_status ON techdb_example(status);
CREATE INDEX IF NOT EXISTS idx_example_created ON techdb_example(x_dateCreated);

Tables TechDB du Socle

Le Socle V004 definit 5 tables techniques:

techdb_offsets

Stockage des offsets de consommation (Kafka, NATS, etc.)

CREATE TABLE IF NOT EXISTS techdb_offsets (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    offset_key VARCHAR(255) NOT NULL UNIQUE,
    topic VARCHAR(255) NOT NULL,
    partition_id INT DEFAULT 0,
    offset_value BIGINT NOT NULL,
    consumer_group VARCHAR(255),
    datas CLOB
);

techdb_worker_state

Etat persistant des Workers

CREATE TABLE IF NOT EXISTS techdb_worker_state (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    worker_name VARCHAR(255) NOT NULL UNIQUE,
    state VARCHAR(50) NOT NULL,
    last_run_at TIMESTAMP WITH TIME ZONE,
    next_run_at TIMESTAMP WITH TIME ZONE,
    error_count INT DEFAULT 0,
    last_error CLOB,
    datas CLOB
);

techdb_events

Evenements techniques

CREATE TABLE IF NOT EXISTS techdb_events (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    event_type VARCHAR(100) NOT NULL,
    source VARCHAR(255) NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    processed_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

techdb_log_buffer

Buffer de logs pour LogForwarder

CREATE TABLE IF NOT EXISTS techdb_log_buffer (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    log_level VARCHAR(20) NOT NULL,
    logger_name VARCHAR(255),
    message CLOB NOT NULL,
    thread_name VARCHAR(255),
    log_timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
    forwarded BOOLEAN DEFAULT FALSE,
    forwarded_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

techdb_kv

Stockage cle-valeur generique

CREATE TABLE IF NOT EXISTS techdb_kv (
    x_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    x_dateCreated TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
    x_dateChanged TIMESTAMP WITH TIME ZONE,
    x_sub VARCHAR(255),
    x_partition VARCHAR(30),
    x_comment CLOB,
    kv_key VARCHAR(512) NOT NULL UNIQUE,
    value_type VARCHAR(50) DEFAULT 'string',
    expires_at TIMESTAMP WITH TIME ZONE,
    datas CLOB
);

Bonnes Pratiques

DO

• Toujours utiliser le format standard x_ pour les champs techniques
• Mettre datas en derniere colonne
• Creer des index sur les colonnes frequemment requetees
• Utiliser TIMESTAMP WITH TIME ZONE pour tous les timestamps
• Documenter le contenu JSON attendu dans datas

DON’T

• Ne pas utiliser AUTO_INCREMENT (syntaxe MySQL)
• Ne pas creer de triggers (gestion applicative)
• Ne pas stocker de BLOBs volumineux (utiliser stockage externe)
• Ne pas utiliser JSONB (non supporte par H2)
• Ne pas omettre les index sur les colonnes de recherche

Migration depuis l’ancien format

Si vous avez des tables existantes avec l’ancien format:

-- 1. Sauvegarder les donnees
CREATE TABLE techdb_events_backup AS SELECT * FROM techdb_events;

-- 2. Supprimer l'ancienne table
DROP TABLE techdb_events;

-- 3. Recreer avec le nouveau format
-- (voir DDL ci-dessus)

-- 4. Migrer les donnees
INSERT INTO techdb_events (event_type, source, processed, processed_at, datas)
SELECT event_type, source, processed, processed_at, payload
FROM techdb_events_backup;

-- 5. Supprimer la sauvegarde
DROP TABLE techdb_events_backup;

Voir aussi

• 21-H2-TECHDB.md – Documentation TechDB complete
• 05-WORKERS.md – Workers TechDB

H2 = dev/tests/outillage – Structure compatible PostgreSQL/H2

Socle V004 – Standard TechDB

03 – Guide de Démarrage Rapide

Version : 4.0.0 Date : 2025-01-25 Temps estimé : 5 minutes

1. Prérequis

• JDK 21+ installé
• Maven 3.9+ installé
• Git (optionnel)

Vérification :

java -version   # java version "21.x.x"
mvn -version    # Maven 3.9.x

2. Installation

Option A : Cloner le projet

git clone <repo>/socle-v004.git
cd socle-v004

Option B : Créer un nouveau projet

mvn archetype:generate \
  -DgroupId=com.mycompany \
  -DartifactId=my-socle-app \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

cd my-socle-app
# Ajouter la dépendance socle-v004 dans pom.xml

3. Configuration minimale

3.1 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>eu.lmvi</groupId>
    <artifactId>socle-v004</artifactId>
    <version>4.0.0</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.1</version>
    </parent>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Web (sans Logback) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-logging</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!-- Log4j2 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-log4j2</artifactId>
        </dependency>

        <!-- LMAX Disruptor (AsyncLoggers) -->
        <dependency>
            <groupId>com.lmax</groupId>
            <artifactId>disruptor</artifactId>
            <version>4.0.0</version>
        </dependency>

        <!-- H2 Database -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>2.2.224</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

3.2 application.yml

spring:
  application:
    name: my-socle-app

socle:
  app_name: ${APP_NAME:my-socle-app}
  version: 4.0.0
  env_name: ${ENV_NAME:DEV}
  region: ${REGION:local}

  # HTTP
  http_port: ${HTTP_PORT:8080}

  # KV Bus
  kv_impl: in_memory

  # Supervisor
  supervisor_enabled: true

  # H2 TechDB
  techdb:
    enabled: true
    url: jdbc:h2:file:./data/techdb;MODE=PostgreSQL
    console:
      enabled: true
      path: /h2-console

logging:
  config: classpath:log4j2.xml

3.3 log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

4. Créer un Worker simple

package com.mycompany.worker;

import eu.lmvi.socle.worker.Worker;
import eu.lmvi.socle.supervisor.Supervisor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
public class HelloWorker implements Worker {

    private static final Logger log = LoggerFactory.getLogger(HelloWorker.class);

    @Autowired
    private Supervisor supervisor;  // Injection du Supervisor

    private int counter = 0;
    private volatile boolean running = false;

    @Override
    public String getName() {
        return "hello-worker";
    }

    @Override
    public void initialize() {
        log.info("HelloWorker initializing...");
    }

    @Override
    public void start() {
        running = true;
        log.info("HelloWorker started!");
    }

    @Override
    public void doWork() {
        if (!running) return;  // Vérifier le flag d'arrêt

        try {
            counter++;
            log.info("Hello from worker! Count: {}", counter);

            // IMPORTANT: Envoyer un heartbeat avec métriques
            supervisor.heartbeat(getName(), getStats());

        } catch (Exception e) {
            log.error("Erreur dans doWork", e);
            // NE PAS propager l'exception
        }
    }

    @Override
    public void stop() {
        running = false;
        log.info("HelloWorker stopped. Final count: {}", counter);
    }

    @Override
    public boolean isHealthy() {
        return running;
    }

    @Override
    public Map<String, Object> getStats() {
        return Map.of(
            "counter", counter,
            "running", running
        );
    }

    @Override
    public long getCycleIntervalMs() {
        return 5000; // doWork() toutes les 5 secondes
    }
}

5. Build et Run

# Build
mvn clean package -DskipTests

# Run
java -jar target/socle-v004-4.0.0.jar

# Ou avec variables d'environnement
APP_NAME=my-app ENV_NAME=PROD java -jar target/socle-v004-4.0.0.jar

6. Vérification

Health check

curl http://localhost:8080/health

Réponse attendue :

{
  "status": "UP",
  "app": "my-socle-app",
  "version": "4.0.0"
}

H2 Console (dev)

Ouvrir : http://localhost:8080/h2-console

• JDBC URL : jdbc:h2:file:./data/techdb
• User : socle
• Password : socle

Logs

Vous devriez voir :

INFO  [main] MainOrchestratorProcess - MOP démarré
INFO  [main] HelloWorker - HelloWorker started!
INFO  [scheduler-1] HelloWorker - Hello from worker! Count: 1
INFO  [scheduler-1] HelloWorker - Hello from worker! Count: 2

StatusDashboard (supervision)

Ouvrir : http://localhost:9374/

Ce dashboard affiche en temps réel :

• L’état de chaque worker (RUNNING, DEGRADED, UNHEALTHY)
• Les métriques transmises par les heartbeats
• L’historique des changements d’état

7. Prochaines étapes

Document	Description
04-CONFIGURATION	Configuration complète
05-WORKERS	Guide des Workers
08-SUPERVISOR	Supervision et heartbeats
21-H2-TECHDB	Base H2 TechDB
22-LOG4J2-LOGFORWARDER	Logging centralisé
27-STATUS-DASHBOARD	Dashboard de supervision
GUIDE-METHODOLOGIQUE	Bonnes pratiques

8. Troubleshooting

Port déjà utilisé

# Changer le port
HTTP_PORT=9090 java -jar target/socle-v004-4.0.0.jar

H2 Console inaccessible

Vérifier que socle.techdb.console.enabled: true dans application.yml.

Logs non visibles

Vérifier que log4j2.xml existe dans src/main/resources/.