Documentation for a newer release is available. View Latest

Selección de versión de flujo basada en contexto

Un ContextBasedVersionSelector es un componente cuya única función es determinar con qué versión debe iniciarse un flujo específico cuando el llamante no especificó una versión en el InitiationInput. En ese escenario, el código generado de manejo de input en tu Domain llamará al ContextBasedVersionSelector configurado con el contexto propagado actual. Si el contexto propagado no se ha establecido explícitamente en el input, se utilizará el contexto de ContextPropagation para seleccionar la versión. Si la versión seleccionada no puede resolverse a una versión de flujo concreta, se utilizará la última versión del flujo (el valor por defecto cuando la selección de versión está deshabilitada).

Entre otras cosas, el módulo ipf-write-starter-core viene con una implementación por defecto de ContextBasedVersionSelector. Para usar el selector por defecto, simplemente inyecta un bean ContextBasedVersionSelector como dependencia en tu Domain:

@Bean
public QuickStartModelDomain initialiseDomain(ActorSystem<?> actorSystem,
    // the dependency on a bean provided by ipf-write-starter-core
    ContextBasedVersionSelector versionSelector) {
    return new QuickStartModelDomain.Builder(actorSystem)
                .withVersionSelector(versionSelector)
                .build();
}

Sigue leyendo para saber más sobre el selector de versión por defecto y cómo configurarlo.

Descripción general del selector de versión por defecto

Para ayudar a determinar la versión del flujo a seleccionar, el selector por defecto se basa en un conjunto de reglas de enrutamiento proporcionadas mediante un almacén de reglas enchufable.

Reglas de selección de versión

Una regla se proporciona usando las siguientes tres piezas de información:

  • la key que debe estar presente en el contexto evaluado

  • el value que debe tener la key del contexto

  • la version si la key con el valor dado

Las reglas en el almacén pueden definirse a dos niveles:

  • por un flujo específico, en cuyo caso aplicarán solo al seleccionar versiones para ese flujo en particular, o

  • globalmente, en cuyo caso aplicarán a todos los flujos

Las reglas definidas por flujo tienen precedencia sobre las reglas definidas globalmente.

Aunque las reglas de enrutamiento no prohíben usar diferentes context keys a nivel global y por flujo, usar la misma context key en todos los niveles resultará en reglas más mantenibles y menos propensas a errores.

Almacenes de reglas

Hay dos tipos de almacenes de reglas disponibles listos para usar:

  • Almacén HOCON, habilitado por defecto, permite especificar tus reglas de enrutamiento mediante propiedades de configuración y no permite ninguna modificación a las reglas después del arranque de la aplicación

  • Almacén Distributed Data, que usa la librería Akka Distributed Data para almacenar y replicar las reglas a todos los nodos del cluster y persistirlas en disco. Las reglas pueden modificarse en cualquier momento y mediante una API HTTP. Al arrancar la aplicación, las reglas se cargan desde disco y se hará fallback a las reglas HOCON si no se encuentran reglas en DData. El almacén Distributed Data se habilita estableciendo ipf.behaviour.version-selection.route-store-type = ddata. Ten en cuenta que hacerlo requerirá añadir los siguientes flags JVM al comando de ejecución --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED debido al uso de LMDB por parte de Akka para almacenamiento persistente (para más detalles ver la documentación oficial)

Configuración de las reglas de selección de versión

Reglas por defecto de selección de versión

La siguiente configuración de reglas se proporciona por defecto:

ipf.behaviour.version-selection {

  // The global flow routing configuration to use when DData store is disabled or empty
  global-rules = { (1)
    // The defaults use the propagated `ipf_version_selection` key to drive version selection
    key-name = ipf_version_selection (2)
    version-rules = [{ (3)
      active-from = "1970-01-01T00:00:00.00Z" (4)
      // The default rules only allow you to pick the oldest or latest versions of flows
      values-to-versions { (5)
        OLDEST = OLDEST
        LATEST = LATEST
        STABLE = OLDEST
        CANARY = LATEST
      }
    }]
  }

  // The per-flow routing configuration to use when DData store is disabled or empty
  per-flow-rules { (6)
    // Example structure your per-flow rule configuration should take:
    //"Flow" = {
    //  key-name = ipf_version_selection
    //  version-rules = [{
    //   active-from = "1970-01-01T00:00:00.00Z"
    //    // The default rules only allow you to pick the oldest or latest versions of flows
    //    values-to-versions {
    //      VALUE1 = V1
    //      VALUE2 = V2
    //    }
    //  }]
    //}
  }
}
1 El bloque de configuración global-rules es efectivamente un bloque de regla de una sola context key.
2 Una regla de context key aplica a una sola key y sus posibles valores, y la propiedad key-name define el nombre de la context key que activa la regla. Por defecto, las reglas globales solo proporcionan soporte para la key ipf_version_selection, que es una context key propagada a nivel de IPF. Las context keys propagadas se detectarán automáticamente en los headers de mensajes de transporte y se incluirán en el contexto actual por los receive connectors.
3 El bloque version-rules proporciona una lista de mapeos entre valores particulares que la context key ipf_version_selection puede tomar y la versión del flujo que queremos seleccionar cuando ese valor se encuentra en el contexto evaluado.
4 Cada entrada en la lista de mapeos version-rules necesita tener una fecha de activación asignada a ella; esto permite añadir reglas con fecha futura. Cuando el mismo valor está presente en múltiples entradas de mapeo, gana la que tenga el active-from más reciente.
5 Los mapeos de valor-a-versión de context key se definen dentro de un bloque values-to-versions. Dado que las reglas globales son independientes del flujo, generalmente faltarán versiones de flujo concretas, pero pueden usarse las versiones placeholder OLDEST y LATEST. Por defecto, cuando ipf_version_selection toma el valor OLDEST o STABLE, se usará la versión más antigua de un flujo en particular, mientras que LATEST y CANARY seleccionarán la versión más reciente de un flujo.
6 No se proporcionan reglas por flujo listas para usar, pero puedes deducir de la configuración de ejemplo que las reglas por flujo usan la misma estructura de context key en la forma de "Flow" = <context-key-config-block>.

Proporcionar reglas de selección de versión personalizadas

Hay dos maneras de personalizar tus reglas de selección de versión:

  1. Proporcionando overrides de configuración vía ipf.conf (o un .conf más alto en la jerarquía). Los overrides de configuración son la única manera de personalizar los almacenes de reglas HOCON y también son necesarios para personalizar los defaults de los almacenes de reglas Distributed Data.

  2. Usando la API de selección de versión para modificar la configuración. La API de versión solo está disponible para los almacenes de reglas Distributed Data.

Los detalles de la API están cubiertos en la página de documentación del API y el resto de esta sección tratará solo HOCON.

Soportar una context key personalizada en reglas globales

Para soportar tu propia context key personalizada en lugar de la key por defecto de IPF ipf_version_selection, simplemente sobreescribe la propiedad completa ipf.behaviour.version-selection.global-rules.key-name:

ipf.behaviour.version-selection.global-rules.key-name = my_custom_context_key

También tendrás que marcar el nuevo header como propagado:

ipf.context-propagation.propagated-supporting-context-keys += my_custom_context_key

Sobrescribir las reglas globales por defecto

Para deshabilitar las reglas globales por defecto, simplemente proporciona un bloque de configuración vacío:

ipf.behaviour.version-selection.global-rules = {}

Para usar mapeos valor-versión diferentes en las reglas globales, simplemente sobreescribe el bloque version-rules con tus propios mapeos:

ipf.behaviour.version-selection.global-rules.version-rules = [{
  active-from = "2024-01-01T00:00:00.00Z"
  values-to-versions {
    // new value mappings
    MY_VALUE_1 = OLDEST
    MY_VALUE_2 = LATEST
    // keeps some of the old ones, too
    STABLE = OLDEST
    CANARY = LATEST
  }
}]

Añadir reglas por flujo

ipf.behaviour.version-selection.per-flow-rules = { (1)
  "Flow" = { (2)
    key-name = ipf_version_selection (3)
    version-rules = [{ (4)
      active-from = "1970-01-01T00:00:00.00Z"
      values-to-versions {
        VALUE1 = V1 (5)
        VALUE2 = V2
      }
    }]
  }
}
1 Añade tus reglas por flujo bajo el bloque de configuración llamado apropiadamente ipf.behaviour.version-selection.per-flow-rules.
2 El bloque de configuración consiste en pares clave-valor "<FlowName>" = <context-key-rule-block>. Una regla de context key aplica a una sola key.
3 Como con las reglas globales, la propiedad key-name define el nombre de la context key que activa la regla. En este ejemplo estamos usando la misma key que usamos para las reglas globales, que es el enfoque sugerido.
4 De nuevo, exactamente como las reglas globales, el bloque version-rules proporciona una lista de mapeos entre valores particulares que la context key puede tomar y la versión del flujo que queremos seleccionar cuando ese valor se encuentra en el contexto evaluado.
5 A diferencia de las reglas globales, aquí se usan versiones concretas de flujo, lo cual no sorprende: poder seleccionar una versión específica de un flujo es la razón principal para especificar reglas por flujo.

Version Selection API

SwaggerUI