Application aliases

Application aliases provides a way to reference an abstract application in the game client which maps to concrete apps depending on rules defined on the server. Rules can use informations in headers of create connection token web requests to decide on which application the request should be routed.

If an alias doesn’t associate the request with any application (the selected rule maps to the null application for instance) create connection token requests return a 503: Not available response.

Managing aliases

From the Web API

Aliases are managed on the grid admin web API.

Listing aliases in an account:

GET: _aliases/{accountId}

Getting an alias:

GET: _aliases/{accountId}/{aliasId}

Creating an alias:

PUT: _aliases/{accountId}/{aliasId}
{
    "rules":[
        {
            "filter":{
                "match":{
                    "field":"http.headers.environment",
                    "value":["debug"]
                }
            },
            "target":"account/appName-debug"
        },
        {
            "target":"account/appName"
        }
    ]
}

Deleting an alias:

DELETE: _aliases/{accountId}/{aliasId}

From the CLI

Listing aliases in an account:

stormancer aliases list -accountId={accountId}

Getting an alias:

stormancer aliases get -accountId={accountId} -id={aliasId}

Deleting an alias:

stormancer aliases delete -accountId={accountId} -id={aliasId}

Alias rules

Aliases contain a list of rules. Each rule redirects to an application or to the null application if the rule should trigger a not available response.

  • Rules are evaluated in the order of the list.

  • Evaluation stops at the first matching rule.

  • To evaluates if a rule matches, the engine runs the filter associated with the rule with the HttpRequest as context.

  • If a rule doesn’t have a filter, it always matches.

  • A rule can only map to an application. Trying to map to an alias results in a 404 Not Found error.

Fields exposed to filters

The only available fields are http headers, with the path http.headers.{headerName}. Keep in mind that headers are parsed by the engine so are expressed as arrays in the context. (see filter example above)

These fields can also be referenced in the target element. If a header is referenced in this way, it will expand to the first element of its values array.

Setting headers in the client

Http headers exposed to alias filters can be defined in the client configuration through the additionalHeaders field:

auto config = Configuration::create(endpoint, account, application);
    config->logger = logger;
    config->serverGamePort = 7777;
    config->maxPeers = static_cast<uint16>(guestsCount + 1);
    config->additionalHeaders["environment"] = "debug";

Note that aliases are only resolved once during a client session, then cached. This way the application an alias resolves to cannot change during the session.

Alias & application name ambiguities

It’s possible to have an alias sharing the same account and id as an application. Suppose that an a cluster contains both and alias and an app named myaccount/foo. Any connection attemp will resolve the id as the alias, and resolve the alias rules.

If a rule in the alias maps it to myaccount/foo, when the rule is selected, the alias will map to the application.