Policies for Async APIs

[BLasan]

A user could attach a policy to manage Messages sent to a Channel. For instance, in WebSub APIs a subscriber might accept a specific structure of the message. In async api definition, we can define the message object. There can be similar use cases that a subscriber or a publisher (in async definition) want to mediate the message sent or received.

[1] https://www.asyncapi.com/docs/concepts/asyncapi-document/structure

version: api-platform.wso2.com/v1
kind: async/websub
metaData:
   name: WebSubHub-API
spec:
  name: WebSub-API-New-API
  version: v1.0
  context: /websubnewapi
  vhosts:
    main:
      default: "*"
    sandbox:
      default: "sandbox-*"
  upstream:
      main:
       url: http://host.docker.internal:9098
      sandbox:
       url: http://host.docker.internal:9098
  channels:
    -  path: /pull-requests
       subscribe:
        policies:
          - name: ModifyHeaders
            version: v1.0.0
            enabled: true
            params:
              requestHeaders:
                - action: SET
                  name: operation-level-req-header
                  value: hello
              responseHeaders:
                - action: SET
                  name: operation-level-res-header
                  value: world
    -  path: /issues
       publish:
         policies:
          - name: ModifyHeaders
            version: v1.0.0
            enabled: true
            params:
              requestHeaders:
                - action: SET
                  name: operation-level-req-header
                  value: hello
              responseHeaders:
                - action: SET
                  name: operation-level-res-header
                  value: world

[BLasan]

@renuka-fernando Are we going to modify the policy definition to support PUB/SUB operations? Or else, we can utilize existing request/response definition for PUB flow(Request/Response flow) and SUB(Request/Response flow) separately.

[BLasan]

We need some internal policies (not user defined ones) to perform query parameter modifications to support WebSubHub protocol as it works with specific well defined parameters[1].

[1] https://www.w3.org/TR/websub/#authenticated-content-distribution

[nuwand]

@BLasan can you provide some specific examples?

In general, I don't think we need policies specific/limited-to event flows.

[BLasan]

In WebSub APIs, yes we only got this SUB path and if a user needs to modify the payload(extracting specific fields out of the original event, adding headers etc), we can go ahead with request/response policy. That will work actually.

For WebSub APIs, as we are using this ballerina WebSubHub, there are few semantics we need to follow. For instance, Ballerina WebSubHub understands the event type by hub.mode parameter. Event source (Event publisher let's say github) might not know this semantics. So when an event comes to the gateway, we need to intercept and modify the headers accordingly. That's also doable with request/response policies.

Consider the WebSocket scenario where you have both PUB, SUB in one route. A user can act as a PUB or SUB at the same time in this scenario. Same route will be used by both partitions. So, this Request/Response concept won't apply for such scenario. This issue arises only if we allow users to add policies as a subscriber or a publisher. Ideally policies should be applicable for a channel[1]. In that case, what ever the message received to channel will be governed with a single(or multiple) Request/Response policy(policies).

This makes sense I guess. So, the definition would be as follows.

[1] https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationsObject

version: api-platform.wso2.com/v1
kind: async/websub
metaData:
   name: WebSubHub-API
spec:
  name: WebSub-API-New-API
  version: v1.0
  context: /websubnewapi
  vhosts:
    main:
      default: "*"
    sandbox:
      default: "sandbox-*"
  upstream:
      main:
       url: http://host.docker.internal:9098
      sandbox:
       url: http://host.docker.internal:9098
  channels:
    -  path: /pull-requests
       policies:
        - name: ModifyHeaders
          version: v1.0.0
          enabled: true
          params:
            requestHeaders:
              - action: SET
                name: operation-level-req-header
                value: hello
            responseHeaders:
              - action: SET
                name: operation-level-res-header
                value: world
    -  path: /issues
       policies:
        - name: ModifyHeaders
          version: v1.0.0
          enabled: true
          params:
            requestHeaders:
              - action: SET
                name: operation-level-req-header
                value: hello
            responseHeaders:
              - action: SET
                name: operation-level-res-header
                value: world