feat(apigatewayv2): websocket - callback url (#15227)

I added property to extract websocket callback endpoint url to WebSocketStage.
I added it simply like existing `url` property.

It's my first time to submit PR.
Please point out any mistakes.

closes #14836 

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-apigatewayv2/README.md

@@ -311,6 +311,15 @@ new WebSocketStage(stack, 'mystage', {
 });
 ```
 
+To retrieve a websocket URL and a callback URL:
+
+```ts
+const webSocketURL = webSocketStage.url;
+// wss://${this.api.apiId}.execute-api.${s.region}.${s.urlSuffix}/${urlPath}
+const callbackURL = webSocketURL.callbackUrl;
+// https://${this.api.apiId}.execute-api.${s.region}.${s.urlSuffix}/${urlPath}
+```
+
 To add any other route:
 
 ```ts

packages/@aws-cdk/aws-apigatewayv2/lib/websocket/stage.ts

@@ -13,6 +13,14 @@ export interface IWebSocketStage extends IStage {
    * The API this stage is associated to.
    */
   readonly api: IWebSocketApi;
+
+  /**
+   * The callback URL to this stage.
+   * You can use the callback URL to send messages to the client from the backend system.
+   * https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html
+   * https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-how-to-call-websocket-api-connections.html
+   */
+  readonly callbackUrl: string;
 }
 
 /**
@@ -57,6 +65,10 @@ export class WebSocketStage extends StageBase implements IWebSocketStage {
       get url(): string {
         throw new Error('url is not available for imported stages.');
       }
+
+      get callbackUrl(): string {
+        throw new Error('callback url is not available for imported stages.');
+      }
     }
     return new Import(scope, id);
   }
@@ -86,11 +98,20 @@ export class WebSocketStage extends StageBase implements IWebSocketStage {
   }
 
   /**
-   * The URL to this stage.
+   * The websocket URL to this stage.
    */
   public get url(): string {
     const s = Stack.of(this);
     const urlPath = this.stageName;
     return `wss://${this.api.apiId}.execute-api.${s.region}.${s.urlSuffix}/${urlPath}`;
   }
+
+  /**
+   * The callback URL to this stage.
+   */
+  public get callbackUrl(): string {
+    const s = Stack.of(this);
+    const urlPath = this.stageName;
+    return `https://${this.api.apiId}.execute-api.${s.region}.${s.urlSuffix}/${urlPath}`;
+  }
 }

packages/@aws-cdk/aws-apigatewayv2/test/websocket/stage.test.ts

@@ -40,5 +40,23 @@ describe('WebSocketStage', () => {
 
     // THEN
     expect(imported.stageName).toEqual(stage.stageName);
+    expect(() => imported.url).toThrow();
+    expect(() => imported.callbackUrl).toThrow();
+  });
+
+  test('callback URL', () => {
+    // GIVEN
+    const stack = new Stack();
+    const api = new WebSocketApi(stack, 'Api');
+
+    // WHEN
+    const defaultStage = new WebSocketStage(stack, 'Stage', {
+      webSocketApi: api,
+      stageName: 'dev',
+    });
+
+    // THEN
+    expect(defaultStage.callbackUrl.endsWith('/dev')).toBe(true);
+    expect(defaultStage.callbackUrl.startsWith('https://')).toBe(true);
   });
 });