channel.ts 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  1. /*
  2. * Copyright 2019 gRPC authors.
  3. *
  4. * Licensed under the Apache License, Version 2.0 (the "License");
  5. * you may not use this file except in compliance with the License.
  6. * You may obtain a copy of the License at
  7. *
  8. * http://www.apache.org/licenses/LICENSE-2.0
  9. *
  10. * Unless required by applicable law or agreed to in writing, software
  11. * distributed under the License is distributed on an "AS IS" BASIS,
  12. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. * See the License for the specific language governing permissions and
  14. * limitations under the License.
  15. *
  16. */
  17. import { ChannelCredentials } from './channel-credentials';
  18. import { ChannelOptions } from './channel-options';
  19. import { ServerSurfaceCall } from './server-call';
  20. import { ConnectivityState } from './connectivity-state';
  21. import type { ChannelRef } from './channelz';
  22. import { Call } from './call-interface';
  23. import { InternalChannel } from './internal-channel';
  24. import { Deadline } from './deadline';
  25. /**
  26. * An interface that represents a communication channel to a server specified
  27. * by a given address.
  28. */
  29. export interface Channel {
  30. /**
  31. * Close the channel. This has the same functionality as the existing
  32. * grpc.Client.prototype.close
  33. */
  34. close(): void;
  35. /**
  36. * Return the target that this channel connects to
  37. */
  38. getTarget(): string;
  39. /**
  40. * Get the channel's current connectivity state. This method is here mainly
  41. * because it is in the existing internal Channel class, and there isn't
  42. * another good place to put it.
  43. * @param tryToConnect If true, the channel will start connecting if it is
  44. * idle. Otherwise, idle channels will only start connecting when a
  45. * call starts.
  46. */
  47. getConnectivityState(tryToConnect: boolean): ConnectivityState;
  48. /**
  49. * Watch for connectivity state changes. This is also here mainly because
  50. * it is in the existing external Channel class.
  51. * @param currentState The state to watch for transitions from. This should
  52. * always be populated by calling getConnectivityState immediately
  53. * before.
  54. * @param deadline A deadline for waiting for a state change
  55. * @param callback Called with no error when a state change, or with an
  56. * error if the deadline passes without a state change.
  57. */
  58. watchConnectivityState(
  59. currentState: ConnectivityState,
  60. deadline: Date | number,
  61. callback: (error?: Error) => void
  62. ): void;
  63. /**
  64. * Get the channelz reference object for this channel. A request to the
  65. * channelz service for the id in this object will provide information
  66. * about this channel.
  67. */
  68. getChannelzRef(): ChannelRef;
  69. /**
  70. * Create a call object. Call is an opaque type that is used by the Client
  71. * class. This function is called by the gRPC library when starting a
  72. * request. Implementers should return an instance of Call that is returned
  73. * from calling createCall on an instance of the provided Channel class.
  74. * @param method The full method string to request.
  75. * @param deadline The call deadline
  76. * @param host A host string override for making the request
  77. * @param parentCall A server call to propagate some information from
  78. * @param propagateFlags A bitwise combination of elements of grpc.propagate
  79. * that indicates what information to propagate from parentCall.
  80. */
  81. createCall(
  82. method: string,
  83. deadline: Deadline,
  84. host: string | null | undefined,
  85. parentCall: ServerSurfaceCall | null,
  86. propagateFlags: number | null | undefined
  87. ): Call;
  88. }
  89. export class ChannelImplementation implements Channel {
  90. private internalChannel: InternalChannel;
  91. constructor(
  92. target: string,
  93. credentials: ChannelCredentials,
  94. options: ChannelOptions
  95. ) {
  96. if (typeof target !== 'string') {
  97. throw new TypeError('Channel target must be a string');
  98. }
  99. if (!(credentials instanceof ChannelCredentials)) {
  100. throw new TypeError(
  101. 'Channel credentials must be a ChannelCredentials object'
  102. );
  103. }
  104. if (options) {
  105. if (typeof options !== 'object') {
  106. throw new TypeError('Channel options must be an object');
  107. }
  108. }
  109. this.internalChannel = new InternalChannel(target, credentials, options);
  110. }
  111. close() {
  112. this.internalChannel.close();
  113. }
  114. getTarget() {
  115. return this.internalChannel.getTarget();
  116. }
  117. getConnectivityState(tryToConnect: boolean) {
  118. return this.internalChannel.getConnectivityState(tryToConnect);
  119. }
  120. watchConnectivityState(
  121. currentState: ConnectivityState,
  122. deadline: Date | number,
  123. callback: (error?: Error) => void
  124. ): void {
  125. this.internalChannel.watchConnectivityState(
  126. currentState,
  127. deadline,
  128. callback
  129. );
  130. }
  131. /**
  132. * Get the channelz reference object for this channel. The returned value is
  133. * garbage if channelz is disabled for this channel.
  134. * @returns
  135. */
  136. getChannelzRef() {
  137. return this.internalChannel.getChannelzRef();
  138. }
  139. createCall(
  140. method: string,
  141. deadline: Deadline,
  142. host: string | null | undefined,
  143. parentCall: ServerSurfaceCall | null,
  144. propagateFlags: number | null | undefined
  145. ): Call {
  146. if (typeof method !== 'string') {
  147. throw new TypeError('Channel#createCall: method must be a string');
  148. }
  149. if (!(typeof deadline === 'number' || deadline instanceof Date)) {
  150. throw new TypeError(
  151. 'Channel#createCall: deadline must be a number or Date'
  152. );
  153. }
  154. return this.internalChannel.createCall(
  155. method,
  156. deadline,
  157. host,
  158. parentCall,
  159. propagateFlags
  160. );
  161. }
  162. }