---
argument_specs:
  main:
    short_description: Sets up a vhost
    description:
      - Sets up a vhost on a web server.
      - Supports reverse proxies, redirects and simple resonses.
      - Currently only supports caddy.
    options:
      vhost_id:
        description: A unique identifier for this vhost. Not visible to end users.
        type: str
        required: true
      vhost_state:
        description: Whether the vhost should exist or not
        type: str
        required: false
        default: present
        choices:
          - present
          - absent
      vhost_type:
        description: Required if vhost_state is present
        type: str
        required: false
        choices:
          - reverse_proxy
          - redirect
          - respond
          - absent
      vhost_domains:
        description: Required if vhost_state is present
        type: list
        required: false
        elements: str
      vhost_web_server:
        description: Defines which server software to use for vhost. This role does nothing if set to none.
        type: str
        required: false
        default: caddy
        choices:
          - caddy
          - none
      vhost_headers:
        description: Dict of response headers and their values
        type: dict
        required: false
        default: {}
      vhost_delete_headers:
        description: List of reponse headers to delete
        type: list
        elements: str
        required: false
        default: []

      vhost_basicauth:
        description: Whether to require basic auth for the vhost
        type: bool
        required: false
        default: false
      vhost_basicauth_users:
        description: A dict of basic auth users and their password hashes. Required if vhost_basicauth is true
        type: dict
        required: false
        default: {}

      vhost_proxy_target_netproto:
        description:
          - Network protocol to use for proxy requests.
          - Only applicable if vhost_type is reverse_proxy.
        type: str
        required: false
        default: tcp
        choices:
          - tcp
          - unix
      vhost_proxy_target_protocol:
        description:
          - Transport protocol (scheme) to use for proxy requests.
          - Only applicable if vhost_type is reverse_proxy.
        type: str
        required: false
        default: http
        choices:
          - http
          - https
      vhost_proxy_target_host:
        description:
          - Host where to proxy requests to.
          - Only applicable if vhost_type is reverse_proxy and vhost_proxy_target_netproto is tcp.
        type: str
        required: false
        default: localhost
      vhost_proxy_target_port:
        description:
          - Port where to proxy requests to.
          - Only applicable if vhost_type is reverse_proxy and vhost_proxy_target_netproto is tcp.
        type: int
        required: false
      vhost_proxy_target_socket:
        description:
          - Unix socket path to proxy requests to.
          - Only applicable if vhost_type is reverse_proxy and vhost_proxy_target_netproto is unix.
        type: str
        required: false
      vhost_proxy_headers:
        description: Dict of request headers and their values to set for proxied requests
        type: dict
        required: false
        default: {}
      vhost_proxy_delete_headers:
        description: List of headers to delete from proxied requests
        type: list
        elements: str
        required: false
        default: []
      vhost_proxy_pass_host_header:
        description: Whether to pass the host header unchanged (true) or change it to the proxy target host (false)
        type: bool
        required: false
        default: true
      vhost_proxy_auth_socket:
        description: >-
          Unix socket path to forward requests to for auhtentication, before
          proxying them
        type: str
        required: false
        default: ""
      vhost_proxy_auth_uri:
        description: >-
          The authentication endpoint of the auth host. Required if
          proxy_auth_socket is defined. Does nothing otherwise.
        type: str
        required: false
        default: ""
      vhost_proxy_auth_unauthorized_redir:
        description: >-
          Where to redirect requests if authentication service returns 401
          unathorized. If not set, returns responses as is.
        type: str
        required: false
        default: ""

      vhost_redirect_target:
        description: "Only applicable if vhost_type is redirect. Example: https://www.domain.tld/location"
        type: str
        required: false
      vhost_redirect_preserve_path:
        description: Whether to keep the original request path
        type: bool
        required: false
        default: false
      vhost_redirect_preserve_query:
        description: Whether to keep the original request query string
        type: bool
        required: false
        default: "{{ vhost_redirect_preserve_path }}"
      redirect_type:
        description: Only applicable if vhost_type is redirect
        type: str
        required: false
        default: temporary
        choices:
          - temporary
          - permanent

      vhost_respond_content:
        description: Content to respond with. Json content can be set as yaml as long as vhost_respond_content_type is set to json
        type: str
        required: false
      vhost_respond_content_type:
        description: Type of the respond content
        type: str
        required: false
        default: plain
        choices:
          - plain
          - json
      vhost_respond_status:
        description: Status code of response
        type: int
        required: false
        default: 200

      vhost_matchers:
        description: >
          List of matchers to handle differently from the default for vhost.
          A matcher matches if all of its conditions match
        type: list
        elements: dict
        required: false
        default: []
        options:
          name:
            description: Name of the matcher used to reference it
            type: str
            required: true

          match_methods:
            description: HTTP methods to match against. Matching one method is enough.
            type: list
            elements: str
            choices:
              - GET
              - HEAD
              - OPTIONS
              - TRACE
              - PUT
              - DELETE
              - POST
              - PATCH
              - CONNECT
            required: false
            default: []
          match_headers:
            description: >-
              Headers to match against.
              If the value begins with ^ and end with $, the value is matched as regex.
            type: dict
            required: false
            default: {}

          type:
            type: str
            required: false
            default: "{{ vhost_type }}"
            choices:
              - reverse_proxy
              - redirect
              - respond
          headers:
            description: Dict of response headers and their values
            type: dict
            required: false
            default: "{{ vhost_headers }}"
          delete_headers:
            description: List of response headers to delete
            type: list
            elements: str
            required: false
            default: "{{ vhost_delete_headers }}"

          basicauth:
            description: Whether to require basic auth for the location
            type: bool
            required: false
            default: "{{ vhost_basicauth }}"
          basicauth_users:
            description: A dict of basic auth users and their password hashes. Required if basicauth is true
            type: dict
            default: "{{ vhost_basicauth_users }}"

          proxy_target_netproto:
            description:
              - Network protocol to use for proxy requests.
              - Only applicable if type is reverse_proxy.
            type: str
            required: false
            default: "{{ vhost_proxy_target_netproto }}"
            choices:
              - tcp
              - unix
          proxy_target_protocol:
            description:
              - Transport protocol (scheme) to use for proxy requests.
              - Only applicable if type is reverse_proxy.
            type: str
            required: false
            default: "{{ vhost_proxy_target_protocol }}"
            choices:
              - http
              - https
          proxy_target_host:
            description: Host where to proxy requests to. Only applicable if type is reverse_proxy
            type: str
            required: false
            default: "{{ vhost_proxy_target_host }}"
          proxy_target_port:
            description: Port where to proxy requests to. Only applicable if type is reverse_proxy.
            type: int
            required: false
            default: "{{ vhost_proxy_target_port if vhost_type == 'reverse_proxy' and vhost_proxy_target_netproto == 'tcp' else 0 }}"
          proxy_target_socket:
            description:
              - Unix socket path to proxy requests to.
              - Only applicable if type is reverse_proxy and proxy_target_netproto is unix.
            type: str
            required: false
            default: "{{ vhost_proxy_target_socket if vhost_type == 'reverse_proxy' and vhost_proxy_target_netproto == 'unix' else '' }}"
          proxy_headers:
            description: Dict of request headers and their values to set for proxied requests
            type: dict
            required: false
            default: "{{ vhost_proxy_headers }}"
          proxy_delete_headers:
            description: List of request headers to delete from proxied requests
            type: list
            elements: str
            required: false
            default: "{{ vhost_proxy_delete_headers }}"
          proxy_pass_host_header:
            description: Whether to pass the host header unchanged (true) or change it to the proxy target host (false)
            type: bool
            required: false
            default: "{{ vhost_proxy_pass_host_header }}"
          proxy_auth_socket:
            description: >-
              Unix socket path to forward requests to for auhtentication, before
              proxying them
            type: str
            required: false
            default: "{{ vhost_proxy_auth_socket }}"
          proxy_auth_uri:
            description: >-
              The authentication endpoint of the auth host. Required if
              proxy_auth_socket is defined. Does nothing otherwise.
            type: str
            required: false
            default: "{{ vhost_proxy_auth_uri }}"
          proxy_auth_unauthorized_redir:
            description: >-
              Where to redirect requests if authentication service returns 401
              unathorized. If not set, returns responses as is.
            type: str
            required: false
            default: "{{ vhost_proxy_auth_unauthorized_redir }}"

          redirect_target:
            description: "Only applicable if vhost_type is redirect. Example: https://www.domain.tld/location"
            type: str
            required: false
            default: "{{ vhost_redirect_target if vhost_type == 'redirect' else '' }}"
          redirect_preserve_path:
            description: Whether to keep the original request path
            type: bool
            required: false
            default: "{{ vhost_redirect_preserve_path }}"
          redirect_preserve_query:
            description: Whether to keep the original request query string
            type: bool
            required: false
            default: "{{ vhost_redirect_preserve_query }}"
          redirect_type:
            description: Only applicable if vhost_type is redirect
            type: str
            required: false
            default: "{{ vhost_redirect_type }}"
            choices:
              - temporary
              - permanent

          respond_content:
            description: >-
              Content to respond with.
              Json content can be set as yaml as long as respond_content_type is set to json.
            type: str
            required: false
            default: "{{ vhost_respond_content if vhost_type == 'respond' else '' }}"
          respond_content_type:
            description: Type of the respond content
            type: str
            required: false
            default: "{{ vhost_respond_content_type }}"
            choices:
              - plain
              - json
          respond_status:
            description: Status code of response
            type: int
            required: false
            default: "{{ vhost_respond_status }}"

      vhost_locations:
        description: List of locations to handle differently from the default for vhost
        type: list
        required: false
        default: []
        elements: dict
        options:
          path:
            description: Path to match. Only supports full paths for now.
            type: str
            required: true
          type:
            type: str
            required: false
            default: "{{ vhost_type }}"
            choices:
              - reverse_proxy
              - redirect
              - respond
          headers:
            description: Dict of response headers and their values
            type: dict
            required: false
            default: "{{ vhost_headers }}"
          delete_headers:
            description: List of response headers to delete
            type: list
            elements: str
            required: false
            default: "{{ vhost_delete_headers }}"

          basicauth:
            description: Whether to require basic auth for the location
            type: bool
            required: false
            default: "{{ vhost_basicauth }}"
          basicauth_users:
            description: A dict of basic auth users and their password hashes. Required if basicauth is true
            type: dict
            default: "{{ vhost_basicauth_users }}"

          proxy_target_netproto:
            description:
              - Network protocol to use for proxy requests.
              - Only applicable if type is reverse_proxy.
            type: str
            required: false
            default: "{{ vhost_proxy_target_netproto }}"
            choices:
              - tcp
              - unix
          proxy_target_protocol:
            description:
              - Transport protocol (scheme) to use for proxy requests.
              - Only applicable if type is reverse_proxy.
            type: str
            required: false
            default: "{{ vhost_proxy_target_protocol }}"
            choices:
              - http
              - https
          proxy_target_host:
            description: Host where to proxy requests to. Only applicable if type is reverse_proxy
            type: str
            required: false
            default: "{{ vhost_proxy_target_host }}"
          proxy_target_port:
            description: Port where to proxy requests to. Only applicable if type is reverse_proxy.
            type: int
            required: false
            default: "{{ vhost_proxy_target_port if vhost_type == 'reverse_proxy' and vhost_proxy_target_netproto == 'tcp' else 0 }}"
          proxy_target_socket:
            description:
              - Unix socket path to proxy requests to.
              - Only applicable if type is reverse_proxy and proxy_target_netproto is unix.
            type: str
            required: false
            default: "{{ vhost_proxy_target_socket if vhost_type == 'reverse_proxy' and vhost_proxy_target_netproto == 'unix' else '' }}"
          proxy_headers:
            description: Dict of request headers and their values to set for proxied requests
            type: dict
            required: false
            default: "{{ vhost_proxy_headers }}"
          proxy_delete_headers:
            description: List of request headers to delete from proxied requests
            type: list
            elements: str
            required: false
            default: "{{ vhost_proxy_delete_headers }}"
          proxy_pass_host_header:
            description: Whether to pass the host header unchanged (true) or change it to the proxy target host (false)
            type: bool
            required: false
            default: "{{ vhost_proxy_pass_host_header }}"
          proxy_auth_socket:
            description: >-
              Unix socket path to forward requests to for auhtentication, before
              proxying them
            type: str
            required: false
            default: "{{ vhost_proxy_auth_socket }}"
          proxy_auth_uri:
            description: >-
              The authentication endpoint of the auth host. Required if
              proxy_auth_socket is defined. Does nothing otherwise.
            type: str
            required: false
            default: "{{ vhost_proxy_auth_uri }}"
          proxy_auth_unauthorized_redir:
            description: >-
              Where to redirect requests if authentication service returns 401
              unathorized. If not set, returns responses as is.
            type: str
            required: false
            default: "{{ vhost_proxy_auth_unauthorized_redir }}"

          redirect_target:
            description: "Only applicable if vhost_type is redirect. Example: https://www.domain.tld/location"
            type: str
            required: false
            default: "{{ vhost_redirect_target if vhost_type == 'redirect' else '' }}"
          redirect_preserve_path:
            description: Whether to keep the original request path
            type: bool
            required: false
            default: "{{ vhost_redirect_preserve_path }}"
          redirect_preserve_query:
            description: Whether to keep the original request query string
            type: bool
            required: false
            default: "{{ vhost_redirect_preserve_query }}"
          redirect_type:
            description: Only applicable if vhost_type is redirect
            type: str
            required: false
            default: "{{ vhost_redirect_type }}"
            choices:
              - temporary
              - permanent

          respond_content:
            description: >-
              Content to respond with.
              Json content can be set as yaml as long as respond_content_type is set to json.
            type: str
            required: false
            default: "{{ vhost_respond_content if vhost_type == 'respond' else '' }}"
          respond_content_type:
            description: Type of the respond content
            type: str
            required: false
            default: "{{ vhost_respond_content_type }}"
            choices:
              - plain
              - json
          respond_status:
            description: Status code of response
            type: int
            required: false
            default: "{{ vhost_respond_status }}"

          matchers:
            description: >
              List of matchers to handle differently from the default for vhost.
              A matcher matches if all of its conditions match.
              Options without a specified default will default to location's corresponding option.
            type: list
            elements: dict
            required: false
            default: "{{ vhost_matchers }}"
            options:
              name:
                description: Name of the matcher used to reference it
                type: str
                required: true

              match_methods:
                description: HTTP methods to match against. Matching one method is enough.
                type: list
                elements: str
                choices:
                  - GET
                  - HEAD
                  - OPTIONS
                  - TRACE
                  - PUT
                  - DELETE
                  - POST
                  - PATCH
                  - CONNECT
                required: false
                default: []
              match_headers:
                description: >-
                  Headers to match against.
                  The value is matched as regex.
                  ^ and $ are implied, so don't add them yourself.
                type: dict
                required: false
                default: {}

              type:
                type: str
                required: false
                choices:
                  - reverse_proxy
                  - redirect
                  - respond
              headers:
                description: Dict of response headers and their values
                type: dict
                required: false
              delete_headers:
                description: List of response headers to delete
                type: list
                elements: str
                required: false

              basicauth:
                description: Whether to require basic auth for the location
                type: bool
                required: false
              basicauth_users:
                description: A dict of basic auth users and their password hashes. Required if basicauth is true
                type: dict

              proxy_target_netproto:
                description:
                  - Network protocol to use for proxy requests.
                  - Only applicable if type is reverse_proxy.
                type: str
                required: false
                choices:
                  - tcp
                  - unix
              proxy_target_protocol:
                description:
                  - Transport protocol (scheme) to use for proxy requests.
                  - Only applicable if type is reverse_proxy.
                type: str
                required: false
                choices:
                  - http
                  - https
              proxy_target_host:
                description: Host where to proxy requests to. Only applicable if type is reverse_proxy
                type: str
                required: false
              proxy_target_port:
                description: Port where to proxy requests to. Only applicable if type is reverse_proxy.
                type: int
                required: false
              proxy_target_socket:
                description:
                  - Unix socket path to proxy requests to.
                  - Only applicable if type is reverse_proxy and proxy_target_netproto is unix.
                type: str
                required: false
              proxy_headers:
                description: Dict of request headers and their values to set for proxied requests
                type: dict
                required: false
              proxy_delete_headers:
                description: List of request headers to delete from proxied requests
                type: list
                elements: str
                required: false
              proxy_pass_host_header:
                description: Whether to pass the host header unchanged (true) or change it to the proxy target host (false)
                type: bool
                required: false

              redirect_target:
                description: "Only applicable if vhost_type is redirect. Example: https://www.domain.tld/location"
                type: str
                required: false
              redirect_preserve_path:
                description: Whether to keep the original request path
                type: bool
                required: false
              redirect_preserve_query:
                description: Whether to keep the original request query string
                type: bool
                required: false
              redirect_type:
                description: Only applicable if vhost_type is redirect
                type: str
                required: false
                choices:
                  - temporary
                  - permanent

              respond_content:
                description: >-
                  Content to respond with.
                  Json content can be set as yaml as long as respond_content_type is set to json.
                type: str
                required: false
              respond_content_type:
                description: Type of the respond content
                type: str
                required: false
                choices:
                  - plain
                  - json
              respond_status:
                description: Status code of response
                type: int
                required: false