Multi-Protocol VHost Support for Event Gateways

[ShalkiWenushika]

Overview

The Gateway schema in the Admin REST API currently defines a single vhost string field to represent the public-facing hostname of a self-hosted gateway. While this works for gateways that serve a single protocol, the new WebBroker API type introduces multi-protocol support. APIs deployed on an event gateway can be accessed over HTTPS, WSS, SSE, and other web-friendly protocols, each potentially using a different port.

A single string field cannot capture protocol-specific port information, making it impossible for consumers to discover the correct endpoint for a given protocol.

Current State

The Gateway schema (in admin-api.yaml) defines:

Gateway:
  required:
    - name
    - displayName
    - vhost
    - functionalityType
  properties:
    vhost:
      type: string
      description: The vHost of the gateway
      example: demoVHost.org

This means all protocols served by a gateway share the same hostname with no way to differentiate ports.

Options

Option 1 — Reuse and extend the existing VHost schema

The Environment schema already solves this problem by using a vhosts array of VHost objects, where each VHost carries protocol-specific port fields (httpPort, httpsPort, wsPort, wssPort).

The simplest solution is to replace the flat vhost: string field in the Gateway schema with a reference to the same VHost schema and extend VHost with port fields for any additional protocols that need to be supported.

 # Extend VHost schema
  VHost:
    properties:
      host:
        type: string
        example: gateway.example.com
      httpsPort:
        type: integer
        example: 443
      wssPort:
        type: integer
        example: 8099
      ssePort:          # new
        type: integer
        example: 8080

  # Gateway schema change
  Gateway:
    properties:
      vhost:
        $ref: '#/components/schemas/VHost'

Pros: Consistent with how Environment handles vhosts. No new schemas introduced. Extending VHost with ssePort also benefits environments if SSE support is needed there too.

Cons: Reusing the shared VHost schema for a gateway-specific requirement may not be ideal. It also mixes environment-level vhost details with gateway registration details, which represent different concerns.

Option 2 — Introduce a new GatewayVHost schema

Define a structured vhost type specific to the Gateway resource, keeping it decoupled from the Environment's VHost schema:

  GatewayVHost:
    type: object
    required:
      - host
    properties:
      host:
        type: string
        example: gateway.example.com
      httpsPort:
        type: integer
        example: 443
      wssPort:
        type: integer
        example: 8099
      ssePort:
        type: integer
        example: 8080

  # Gateway schema change
  Gateway:
    properties:
      vhost:
        $ref: '#/components/schemas/GatewayVHost'

Pros: Clean separation of concerns. Gateway vhost requirements evolve independently from environment vhosts. New protocols for new API types can be added without touching VHost.

Cons: Introduces a new schema that largely duplicates VHost.

Recommendation

Option 2 — introduce a dedicated GatewayVHost schema.

The Gateway resource is conceptually different from Environment: it represents a self-hosted gateway registered against the admin plane, not a managed deployment environment. Their vhost semantics will likely diverge further as new gateway types are introduced with their own supported protocols.

Extending the shared VHost schema (Option 1) risks coupling these two concerns. A dedicated GatewayVHost gives a clean, evolvable contract for gateway registration without affecting existing schemas.

As a starting point, GatewayVHost can mirror the structure of VHost, while allowing additional protocol-specific fields to be added in the future. With this approach, support for new protocols and API types would only require extending a single schema.

However, this schema change will require updates to the UI calls and DB for other self-hosted gateways as well.

Appreciate any feedback here before we proceed with the schema changes and implementation.

[malinthaprasan]

Suggesting a 3rd option:

Option 3 — Flat endpoints array

Instead of a single vhost object with fixed per-protocol port fields, model the gateway's exposure as a list of self-contained {host, protocol, port} bindings:

GatewayEndpoint:
  type: object
  required: [host, protocol, port]
  properties:
    host:
      type: string
      example: gateway.example.com
    protocol:
      type: string
      enum: [https, wss, sse]
      example: https
    port:
      type: integer
      format: int32
      minimum: 1
      maximum: 65535
      example: 443

Gateway:
  required: [name, displayName, endpoints, functionalityType]
  properties:
    endpoints:
      type: array
      minItems: 1
      uniqueItems: true
      items:
        $ref: '#/components/schemas/GatewayEndpoint'

Example:

endpoints:
  - { host: api.example.com,    protocol: https, port: 443 }
  - { host: events.example.com, protocol: wss,   port: 8099 }
  - { host: events.example.com, protocol: sse,   port: 8080 }

Why over Options 1 & 2

• Multi-host: a gateway can serve more than one hostname so this may be able to address future requirements as well.
• Minimal schema change per protocol: when adding a new protocol we can just add a new enum entry and add a new array entry to the endpoint list.

Notes

• Better to enforce a uniqueness is per (host, protocol) pair
• We can keep the current vhost working as a deprecated field

[ShalkiWenushika]

We have decided to proceed with Option 3: migrate the data from the current vhost column to the newly added endpoints column, and then remove the vhost column from the database.