# server-hosts

Source: https://apigenie.pl/docs/linter/asyncapi/rules/server-hosts

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**.

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

## Examples

**Good**.

```yaml
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.

```yaml
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.