Skip to content

Athena::Mercure::Bundle::Schema#

Represents the possible properties used to configure and customize the Mercure integration. See the Getting Started docs for more information on how the bundle system works in Athena.

A full example showing all properties is as follows:

ADI.configure({
  mercure: {
    hubs: {
      default: {
        url:        "https://internal-hub/.well-known/mercure",
        public_url: "https://hub.example.com/.well-known/mercure",
        jwt:        {
          # Provide *secret* to generate JWTs dynamically via a token factory...
          secret:     "my-jwt-secret",
          publish:    ["*"],
          subscribe:  ["https://example.com/books/1"],
          algorithm:  :hs256,
          passphrase: "",
          claims:     {
            "iss"       => "https://example.com",
            "sub"       => "urn:example:app",
            "client_id" => "https://example.com",
          },

          # ...or provide *value* to use a static JWT token directly.
          # value: "eyJhbGciOiJIUzI1NiJ9...",
        },
        protocol_version: "1.0",
        cookie_name:      "__Secure-mercure_access_token",
      },
      separate_keys: {
        url:       "https://hub.example.com/.well-known/mercure",
        publisher: {
          secret: "my-publisher-jwt-secret",
          topics: ["*"],
          claims: {"iss" => "https://example.com", "sub" => "urn:example:app", "client_id" => "https://example.com"},
        },
        subscriber: {
          secret: "my-subscriber-jwt-secret",
          claims: {"iss" => "https://example.com", "sub" => "urn:example:app", "client_id" => "https://example.com"},
        },
      },
    },
    default_hub:             "default",
    default_cookie_lifetime: 1.hour,
  },
})

Configuration Properties

hubs#

type:

Hash(K, V)

default:

{__nil: nil}

Named Mercure hub definitions. Each hub requires a url, and either a jwt or a publisher configuration.

Todo

Support publishing the updates of a hub via a dedicated HTTP::Client service, via http_client. Configuring it is currently an error.

This property consists of a map of key/value pairs where each value has the following properties:

url#

type:

String

Required

The internal URL used by the server to publish updates to this hub. Should be set via ENV var.

public_url#

type:

String | ::Nil

default:

nil

The public URL exposed to clients via the Link header for hub discovery. Falls back to url if not set. Useful when the internal hub URL differs from the one clients should connect to. Should be set via ENV var.

jwt#

type:

JWT

default:

{value: nil}

The JWT configuration used for both publishing and subscribing, see JWT.

This property consists of an object with the following properties:

value#
type:

String | ::Nil

default:

nil

A pre-built static JWT token string provided via AMC::TokenProvider::Static. When set, the token is used as-is to publish updates.

provider#
type:

String | ::Nil

default:

nil

The ID of a service implementing AMC::TokenProvider::Interface that provides the token used to publish updates.

factory#
type:

String | ::Nil

default:

nil

The ID of a service implementing AMC::TokenFactory::Interface used to generate tokens, instead of secret.

secret#
type:

String | ::Nil

default:

nil

The secret key used to sign JWTs generated via AMC::TokenFactory::JWT. Should be set via ENV var.

passphrase#
type:

String

Required

Passphrase for the secret key, if the algorithm requires one (e.g. RSA).

algorithm#
type:

Symbol

default:

hs256

The signing algorithm used to encode the JWT, as the name of a JWT::Algorithm member, such as :hs256 or :rs256.

claims#
type:

Hash(String, String | Array(String))

default:

{} of String => String | Array(String)

Additional claims of the generated JWTs. Under the Mercure protocol 1.0, the iss, sub, and client_id claims are required when using secret, and aud defaults to the hub's public_url, or url.

publish#
type:

Array(String)

default:

[] of String

Topic selectors that the token used to publish updates is allowed to publish to.

subscribe#
type:

Array(String)

default:

[] of String

Topic selectors that the token used to publish updates is allowed to subscribe to.

publisher#

type:

Publisher

default:

{value: nil}

The JWT configuration used for publishing, as an alternative to jwt, see Publisher.

This property consists of an object with the following properties:

value#
type:

String | ::Nil

default:

nil

A pre-built static JWT token string provided via AMC::TokenProvider::Static.

provider#
type:

String | ::Nil

default:

nil

The ID of a service implementing AMC::TokenProvider::Interface that provides the token.

factory#
type:

String | ::Nil

default:

nil

The ID of a service implementing AMC::TokenFactory::Interface used to generate the token, instead of secret.

topics#
type:

Array(String)

default:

[] of String

Topic selectors that the generated token is allowed to publish to.

secret#
type:

String | ::Nil

default:

nil

The secret key used to sign the token generated via AMC::TokenFactory::JWT. Should be set via ENV var.

passphrase#
type:

String

Required

Passphrase for the secret key, if the algorithm requires one (e.g. RSA).

algorithm#
type:

Symbol

default:

hs256

The signing algorithm used to encode the JWT, as the name of a JWT::Algorithm member, such as :hs256 or :rs256.

claims#
type:

Hash(String, String | Array(String))

default:

{} of String => String | Array(String)

Additional claims of the generated token, see the claims of jwt.

subscriber#

type:

Subscriber

default:

{factory: nil}

The JWT configuration used for subscribing, as an alternative to jwt, see Subscriber.

This property consists of an object with the following properties:

factory#
type:

String | ::Nil

default:

nil

The ID of a service implementing AMC::TokenFactory::Interface used to generate the tokens, instead of secret.

secret#
type:

String | ::Nil

default:

nil

The secret key used to sign the tokens generated via AMC::TokenFactory::JWT. Should be set via ENV var.

passphrase#
type:

String

Required

Passphrase for the secret key, if the algorithm requires one (e.g. RSA).

algorithm#
type:

Symbol

default:

hs256

The signing algorithm used to encode the JWTs, as the name of a JWT::Algorithm member, such as :hs256 or :rs256.

claims#
type:

Hash(String, String | Array(String))

default:

{} of String => String | Array(String)

Additional claims of the generated tokens, see the claims of jwt.

protocol_version#

type:

String

default:

1.0

The version of the Mercure protocol this hub speaks, "1.0" or "0.x". Affects the default cookie_name, and the claims of the tokens generated via secret.

cookie_name#

type:

String | ::Nil

default:

nil

The name of the subscriber authorization cookie. Defaults to __Secure-mercure_access_token under the Mercure protocol 1.0, or mercure_access_token if the framework.debug parameter is true, as browsers drop __Secure- cookies over plain HTTP. Defaults to mercureAuthorization under the Mercure protocol 0.x.

default_hub#

type:

String | ::Nil

default:

nil

The name of the hub to use when none is specified. Defaults to the first defined hub if not explicitly set.

type:

Time::Span

default:

1.hour

Default lifetime for authorization cookies set via AMC::Bundle::Authorization.