server-hosts
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error
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 pathwhenhostcontains://or/. The scheme belongs toprotocol, and the path topathname.Server host is not lower casewhenhostcontains upper-case letters. Host names are case-insensitive, and lower case is their canonical form.Server protocol is not lower casewhenprotocolcontains upper-case letters.Server uses an insecure protocol (<protocol>)when the protocol ishttporws, unless the host islocalhost,127.0.0.1or[::1](with or without a port). Usehttpsorwssinstead.
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
--fix 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.
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.asyncapi has the details.
commands:
lint:
asyncapi:
rules:
server-hosts: off