server-hosts (AsyncAPI linter rule)

Since 0.9.0 · fixed by --fix

This rule checks that the servers of an AsyncAPI document have well-formed hosts and protocols, and that they use secure protocols.

Rule Details

In AsyncAPI 3.x, a server is described by separate host, protocol and pathname fields. A common mistake, especially when migrating from AsyncAPI 2.x (where servers had a single url), is to put a complete URL into host.

The server-hosts rule checks every server in the root servers map and reports:

Server host must not contain a scheme or a path when host contains :// or /. The scheme belongs to protocol, and the path to pathname.
Server host is not lower case when host contains upper-case letters. Host names are case-insensitive, and lower case is their canonical form.
Server protocol is not lower case when protocol contains upper-case letters.
Server uses an insecure protocol (<protocol>) when the protocol is http or ws, unless the host is localhost, 127.0.0.1 or [::1] (with or without a port). Use https or wss instead.

Server variables (e.g. {environment} in {environment}.your-company.com) are not required to be lower case.

Configuration

The configuration block is an object with a single optional boolean property, upgradeInsecure. When it is true, the automatic fix also replaces insecure protocols with their secure variants (see “Automatic fixes”). The default value is false.

Configuration Example.

version: "1.0"
commands:
  lint:
    asyncapi:
      rules:
        server-hosts:
          - warning
          - upgradeInsecure: true

Examples

Good.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
servers:
  production:
    host: broker.your-company.com:9092
    protocol: kafka
  staging:
    host: "{environment}.your-company.com"
    protocol: wss
    pathname: /events
    variables:
      environment:
        default: staging
  local:
    host: localhost:8080
    protocol: ws

Bad. The first server has an upper-case host and protocol, the second one puts a complete URL into host, and the third one uses an insecure protocol.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
servers:
  production:
    host: Broker.Your-Company.com:9092
    protocol: Kafka
  staging:
    host: wss://staging.your-company.com/events
    protocol: wss
  public:
    host: events.your-company.com
    protocol: ws

Automatic fixes

When invoked with --fix, this rule converts hosts and protocols to lower case, leaving server variables untouched. Hosts that contain a scheme or a path are not changed, as the rule cannot tell how to split them.

If upgradeInsecure is true, the fix also replaces http with https, and ws with wss, for all servers other than localhost, 127.0.0.1 and [::1]. Make sure that the servers actually support the secure protocol before enabling this option.

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with AsyncAPI 3.x documents. AsyncAPI 2.x documents are rejected by the reader and are not linted.