grpc 1.43.1 → 1.46.2

data/include/grpc/event_engine/event_engine.h

@@ -378,7 +378,7 @@ class EventEngine {
   virtual bool Cancel(TaskHandle handle) = 0;
 };
 
-/// Replace gRPC's default EventEngine factory
+/// Replace gRPC's default EventEngine factory.
 ///
 /// Applications may call \a SetDefaultEventEngineFactory at any time to replace
 /// the default factory used within gRPC. EventEngines will be created when
@@ -390,7 +390,7 @@ class EventEngine {
 void SetDefaultEventEngineFactory(
     const std::function<std::unique_ptr<EventEngine>()>* factory);
 
-/// Create an EventEngine using the default factory
+/// Create an EventEngine using the default factory.
 std::unique_ptr<EventEngine> CreateEventEngine();
 
 }  // namespace experimental

data/include/grpc/grpc.h

@@ -295,15 +295,41 @@ GRPCAPI void grpc_channel_get_info(grpc_channel* channel,
     to non-experimental or remove it. */
 GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel* channel);
 
-/** Create a client channel to 'target'. Additional channel level configuration
-    MAY be provided by grpc_channel_args, though the expectation is that most
-    clients will want to simply pass NULL. The user data in 'args' need only
-    live through the invocation of this function. However, if any args of the
-    'pointer' type are passed, then the referenced vtable must be maintained
-    by the caller until grpc_channel_destroy terminates. See grpc_channel_args
-    definition for more on this. */
-GRPCAPI grpc_channel* grpc_insecure_channel_create(
-    const char* target, const grpc_channel_args* args, void* reserved);
+/** --- grpc_channel_credentials object. ---
+
+   A channel credentials object represents a way to authenticate a client on a
+   channel. Different types of channel credentials are declared in
+   grpc_security.h. */
+
+typedef struct grpc_channel_credentials grpc_channel_credentials;
+
+/** Releases a channel credentials object.
+   The creator of the credentials object is responsible for its release. */
+
+GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);
+
+/** --- grpc_server_credentials object. ---
+
+   A server credentials object represents a way to authenticate a server.
+   Different types of server credentials are declared in grpc_security.h. */
+
+typedef struct grpc_server_credentials grpc_server_credentials;
+
+/** Releases a server_credentials object.
+   The creator of the server_credentials object is responsible for its release.
+   */
+GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds);
+
+/** Creates a secure channel using the passed-in credentials. Additional
+    channel level configuration MAY be provided by grpc_channel_args, though
+    the expectation is that most clients will want to simply pass NULL. The
+    user data in 'args' need only live through the invocation of this function.
+    However, if any args of the 'pointer' type are passed, then the referenced
+    vtable must be maintained by the caller until grpc_channel_destroy
+    terminates. See grpc_channel_args definition for more on this. */
+GRPCAPI grpc_channel* grpc_channel_create(const char* target,
+                                          grpc_channel_credentials* creds,
+                                          const grpc_channel_args* args);
 
 /** Create a lame client: this client fails every operation attempted on it. */
 GRPCAPI grpc_channel* grpc_lame_client_channel_create(
@@ -444,11 +470,11 @@ GRPCAPI void grpc_server_config_fetcher_destroy(
 GRPCAPI void grpc_server_set_config_fetcher(
     grpc_server* server, grpc_server_config_fetcher* config_fetcher);
 
-/** Add a HTTP2 over plaintext over tcp listener.
-    Returns bound port number on success, 0 on failure.
-    REQUIRES: server not started */
-GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server* server,
-                                                const char* addr);
+/** Add a HTTP2 over an encrypted link over tcp listener.
+   Returns bound port number on success, 0 on failure.
+   REQUIRES: server not started */
+GRPCAPI int grpc_server_add_http2_port(grpc_server* server, const char* addr,
+                                       grpc_server_credentials* creds);
 
 /** Start a server - tells all listeners to start listening */
 GRPCAPI void grpc_server_start(grpc_server* server);

data/include/grpc/grpc_posix.h

@@ -23,6 +23,7 @@
 
 #include <stddef.h>
 
+#include <grpc/grpc.h>
 #include <grpc/impl/codegen/grpc_types.h>
 
 #ifdef __cplusplus
@@ -35,25 +36,25 @@ extern "C" {
  * functionality on top of GRPC Core.
  */
 
-/** Create a client channel to 'target' using file descriptor 'fd'. The 'target'
-    argument will be used to indicate the name for this channel. See the comment
-    for grpc_insecure_channel_create for description of 'args' argument. */
-GRPCAPI grpc_channel* grpc_insecure_channel_create_from_fd(
-    const char* target, int fd, const grpc_channel_args* args);
-
-/** Add the connected communication channel based on file descriptor 'fd' to the
-    'server'. The 'fd' must be an open file descriptor corresponding to a
-    connected socket. Events from the file descriptor may come on any of the
-    server completion queues (i.e completion queues registered via the
-    grpc_server_register_completion_queue API).
-
-    The 'reserved' pointer MUST be NULL.
-
-    TODO(hork): add channel_args to this API to allow endpoints and transports
-    created in this function to participate in the resource quota feature.
-    */
-GRPCAPI void grpc_server_add_insecure_channel_from_fd(grpc_server* server,
-                                                      void* reserved, int fd);
+/** Create a secure channel to 'target' using file descriptor 'fd' and passed-in
+    credentials. The 'target' argument will be used to indicate the name for
+    this channel. Note that this API currently only supports insecure channel
+    credentials. Using other types of credentials will result in a failure. */
+GRPCAPI grpc_channel* grpc_channel_create_from_fd(
+    const char* target, int fd, grpc_channel_credentials* creds,
+    const grpc_channel_args* args);
+
+/** Add the connected secure communication channel based on file descriptor 'fd'
+   to the 'server' and server credentials 'creds'. The 'fd' must be an open file
+   descriptor corresponding to a connected socket. Events from the file
+   descriptor may come on any of the server completion queues (i.e completion
+   queues registered via the grpc_server_register_completion_queue API).
+   Note that this API currently only supports inseure server credentials
+   Using other types of credentials will result in a failure.
+   TODO(hork): add channel_args to this API to allow endpoints and transports
+   created in this function to participate in the resource quota feature. */
+GRPCAPI void grpc_server_add_channel_from_fd(grpc_server* server, int fd,
+                                             grpc_server_credentials* creds);
 
 #ifdef __cplusplus
 }

data/include/grpc/grpc_security.h

@@ -131,17 +131,6 @@ typedef struct grpc_call_credentials grpc_call_credentials;
    The creator of the credentials object is responsible for its release. */
 GRPCAPI void grpc_call_credentials_release(grpc_call_credentials* creds);
 
-/** --- grpc_channel_credentials object. ---
-
-   A channel credentials object represents a way to authenticate a client on a
-   channel.  */
-
-typedef struct grpc_channel_credentials grpc_channel_credentials;
-
-/** Releases a channel credentials object.
-   The creator of the credentials object is responsible for its release. */
-GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials* creds);
-
 /** Creates default credentials to connect to a google gRPC service.
    WARNING: Do NOT use this credentials to connect to a non-google service as
    this could result in an oauth2 token leak. The security level of the
@@ -478,30 +467,6 @@ GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin(
     grpc_metadata_credentials_plugin plugin,
     grpc_security_level min_security_level, void* reserved);
 
-/** --- Secure channel creation. --- */
-
-/** Creates a secure channel using the passed-in credentials. Additional
-    channel level configuration MAY be provided by grpc_channel_args, though
-    the expectation is that most clients will want to simply pass NULL. The
-    user data in 'args' need only live through the invocation of this function.
-    However, if any args of the 'pointer' type are passed, then the referenced
-    vtable must be maintained by the caller until grpc_channel_destroy
-    terminates. See grpc_channel_args definition for more on this. */
-GRPCAPI grpc_channel* grpc_secure_channel_create(
-    grpc_channel_credentials* creds, const char* target,
-    const grpc_channel_args* args, void* reserved);
-
-/** --- grpc_server_credentials object. ---
-
-   A server credentials object represents a way to authenticate a server.  */
-
-typedef struct grpc_server_credentials grpc_server_credentials;
-
-/** Releases a server_credentials object.
-   The creator of the server_credentials object is responsible for its release.
-   */
-GRPCAPI void grpc_server_credentials_release(grpc_server_credentials* creds);
-
 /** Server certificate config object holds the server's public certificates and
    associated private keys, as well as any CA certificates needed for client
    certificate validation (if applicable). Create using
@@ -599,15 +564,6 @@ GRPCAPI grpc_server_credentials*
 grpc_ssl_server_credentials_create_with_options(
     grpc_ssl_server_credentials_options* options);
 
-/** --- Server-side secure ports. --- */
-
-/** Add a HTTP2 over an encrypted link over tcp listener.
-   Returns bound port number on success, 0 on failure.
-   REQUIRES: server not started */
-GRPCAPI int grpc_server_add_secure_http2_port(grpc_server* server,
-                                              const char* addr,
-                                              grpc_server_credentials* creds);
-
 /** --- Call specific credentials. --- */
 
 /** Sets a credentials to a call. Can only be called on the client side before
@@ -920,6 +876,16 @@ GRPCAPI void grpc_tls_credentials_options_set_identity_cert_name(
 GRPCAPI void grpc_tls_credentials_options_set_cert_request_type(
     grpc_tls_credentials_options* options,
     grpc_ssl_client_certificate_request_type type);
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * If set, gRPC will read all hashed x.509 CRL files in the directory and
+ * enforce the CRL files on all TLS handshakes. Only supported for OpenSSL
+ * version > 1.1.
+ * It is used for experimental purpose for now and subject to change.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_crl_directory(
+    grpc_tls_credentials_options* options, const char* crl_directory);
 
 /**
  * EXPERIMENTAL API - Subject to change
@@ -1177,14 +1143,14 @@ grpc_server_credentials* grpc_tls_server_credentials_create(
  *
  * This method creates an insecure channel credentials object.
  */
-grpc_channel_credentials* grpc_insecure_credentials_create();
+GRPCAPI grpc_channel_credentials* grpc_insecure_credentials_create();
 
 /**
  * EXPERIMENTAL API - Subject to change
  *
  * This method creates an insecure server credentials object.
  */
-grpc_server_credentials* grpc_insecure_server_credentials_create();
+GRPCAPI grpc_server_credentials* grpc_insecure_server_credentials_create();
 
 /**
  * EXPERIMENTAL API - Subject to change
@@ -1226,9 +1192,9 @@ typedef struct grpc_authorization_policy_provider
 
 /**
  * EXPERIMENTAL - Subject to change.
- * Creates a grpc_authorization_policy_provider using SDK authorization policy
+ * Creates a grpc_authorization_policy_provider using gRPC authorization policy
  * from static string.
- * - authz_policy is the input SDK authorization policy.
+ * - authz_policy is the input gRPC authorization policy.
  * - code is the error status code on failure. On success, it equals
  *   GRPC_STATUS_OK.
  * - error_details contains details about the error if any. If the
@@ -1242,9 +1208,9 @@ grpc_authorization_policy_provider_static_data_create(
 
 /**
  * EXPERIMENTAL - Subject to change.
- * Creates a grpc_authorization_policy_provider by watching for SDK
+ * Creates a grpc_authorization_policy_provider by watching for gRPC
  * authorization policy changes in filesystem.
- * - authz_policy is the file path of SDK authorization policy.
+ * - authz_policy is the file path of gRPC authorization policy.
  * - refresh_interval_sec is the amount of time the internal thread would wait
  *   before checking for file updates.
  * - code is the error status code on failure. On success, it equals
@@ -1266,6 +1232,26 @@ grpc_authorization_policy_provider_file_watcher_create(
 GRPCAPI void grpc_authorization_policy_provider_release(
     grpc_authorization_policy_provider* provider);
 
+/** --- TLS session key logging. ---
+ * Experimental API to control tls session key logging. Tls session key logging
+ * is expected to be used only for debugging purposes and never in production.
+ * Tls session key logging is only enabled when:
+ *  At least one grpc_tls_credentials_options object is assigned a tls session
+ *  key logging file path using the API specified below.
+ */
+
+/**
+ * EXPERIMENTAL API - Subject to change.
+ * Configures a grpc_tls_credentials_options object with tls session key
+ * logging capability. TLS channels using these credentials have tls session
+ * key logging enabled.
+ * - options is the grpc_tls_credentials_options object
+ * - path is a string pointing to the location where TLS session keys would be
+ *   stored.
+ */
+GRPCAPI void grpc_tls_credentials_options_set_tls_session_key_log_file_path(
+    grpc_tls_credentials_options* options, const char* path);
+
 #ifdef __cplusplus
 }
 #endif

data/include/grpc/impl/codegen/compression_types.h

@@ -60,8 +60,6 @@ typedef enum {
   GRPC_COMPRESS_NONE = 0,
   GRPC_COMPRESS_DEFLATE,
   GRPC_COMPRESS_GZIP,
-  /* EXPERIMENTAL: Stream compression is currently experimental. */
-  GRPC_COMPRESS_STREAM_GZIP,
   /* TODO(ctiller): snappy */
   GRPC_COMPRESS_ALGORITHMS_COUNT
 } grpc_compression_algorithm;

data/include/grpc/impl/codegen/grpc_types.h

@@ -219,7 +219,7 @@ typedef struct {
   "grpc.http2.min_ping_interval_without_data_ms"
 /** Channel arg to override the http2 :scheme header */
 #define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme"
-/** How many pings can we send before needing to send a
+/** How many pings can the client send before needing to send a
    data/header frame? (0 indicates that an infinite number of
    pings can be sent without sending a data frame or header frame) */
 #define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \
@@ -241,8 +241,8 @@ typedef struct {
     not receive the ping ack, it will close the transport. Int valued,
     milliseconds. */
 #define GRPC_ARG_KEEPALIVE_TIMEOUT_MS "grpc.keepalive_timeout_ms"
-/** Is it permissible to send keepalive pings without any outstanding streams.
-    Int valued, 0(false)/1(true). */
+/** Is it permissible to send keepalive pings from the client without any
+   outstanding streams. Int valued, 0(false)/1(true). */
 #define GRPC_ARG_KEEPALIVE_PERMIT_WITHOUT_CALLS \
   "grpc.keepalive_permit_without_calls"
 /** Default authority to pass if none specified on call construction. A string.
@@ -384,11 +384,10 @@ typedef struct {
     "latency". */
 #define GRPC_ARG_OPTIMIZATION_TARGET "grpc.optimization_target"
 /** Enables retry functionality.  Defaults to true.  When enabled,
-    configurable retries are enabled when they are configured via the
-    service config.  For details, see:
+    transparent retries will be performed as appropriate, and configurable
+    retries are enabled when they are configured via the service config.
+    For details, see:
       https://github.com/grpc/proposal/blob/master/A6-client-retries.md
-    NOTE: Transparent retries are not yet implemented.  When they are
-          implemented, they will also be enabled by this arg.
     NOTE: Hedging functionality is not yet implemented, so those
           fields in the service config will currently be ignored.  See
           also the GRPC_ARG_EXPERIMENTAL_ENABLE_HEDGING arg below.
@@ -422,10 +421,14 @@ typedef struct {
 /** If set, inhibits health checking (which may be enabled via the
  *  service config.) */
 #define GRPC_ARG_INHIBIT_HEALTH_CHECKING "grpc.inhibit_health_checking"
-/** If set, the channel's resolver is allowed to query for SRV records.
- * For example, this is useful as a way to enable the "grpclb"
- * load balancing policy. Note that this only works with the "ares"
- * DNS resolver, and isn't supported by the "native" DNS resolver. */
+/** If enabled, the channel's DNS resolver queries for SRV records.
+ *  This is useful only when using the "grpclb" load balancing policy,
+ *  as described in the following documents:
+ *   https://github.com/grpc/proposal/blob/master/A5-grpclb-in-dns.md
+ *   https://github.com/grpc/proposal/blob/master/A24-lb-policy-config.md
+ *   https://github.com/grpc/proposal/blob/master/A26-grpclb-selection.md
+ *  Note that this works only with the "ares" DNS resolver; it isn't supported
+ *  by the "native" DNS resolver. */
 #define GRPC_ARG_DNS_ENABLE_SRV_QUERIES "grpc.dns_enable_srv_queries"
 /** If set, determines an upper bound on the number of milliseconds that the
  * c-ares based DNS resolver will wait on queries before cancelling them.
@@ -445,6 +448,12 @@ typedef struct {
     gRPC authorization check. */
 #define GRPC_ARG_AUTHORIZATION_POLICY_PROVIDER \
   "grpc.authorization_policy_provider"
+/** EXPERIMENTAL. Updates to a server's configuration from a config fetcher (for
+ * example, listener updates from xDS) cause all older connections to be
+ * gracefully shut down (i.e., "drained") with a grace period configured by this
+ * channel arg. Int valued, milliseconds. Defaults to 10 minutes.*/
+#define GRPC_ARG_SERVER_CONFIG_CHANGE_DRAIN_GRACE_TIME_MS \
+  "grpc.experimental.server_config_change_drain_grace_time_ms"
 /** \} */
 
 /** Result of a grpc call. If the caller satisfies the prerequisites of a
@@ -509,12 +518,8 @@ typedef enum grpc_call_error {
 
 /** Initial metadata flags */
 /** These flags are to be passed to the `grpc_op::flags` field */
-/** Signal that the call is idempotent */
-#define GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST (0x00000010u)
 /** Signal that the call should not return UNAVAILABLE before it has started */
 #define GRPC_INITIAL_METADATA_WAIT_FOR_READY (0x00000020u)
-/** Signal that the call is cacheable. GRPC is free to use GET verb */
-#define GRPC_INITIAL_METADATA_CACHEABLE_REQUEST (0x00000040u)
 /** Signal that GRPC_INITIAL_METADATA_WAIT_FOR_READY was explicitly set
     by the calling application. */
 #define GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET (0x00000080u)
@@ -522,12 +527,10 @@ typedef enum grpc_call_error {
 #define GRPC_INITIAL_METADATA_CORKED (0x00000100u)
 
 /** Mask of all valid flags */
-#define GRPC_INITIAL_METADATA_USED_MASK                  \
-  (GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST |            \
-   GRPC_INITIAL_METADATA_WAIT_FOR_READY |                \
-   GRPC_INITIAL_METADATA_CACHEABLE_REQUEST |             \
-   GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET | \
-   GRPC_INITIAL_METADATA_CORKED | GRPC_WRITE_THROUGH)
+#define GRPC_INITIAL_METADATA_USED_MASK                                  \
+  (GRPC_INITIAL_METADATA_WAIT_FOR_READY_EXPLICITLY_SET |                 \
+   GRPC_INITIAL_METADATA_WAIT_FOR_READY | GRPC_INITIAL_METADATA_CORKED | \
+   GRPC_WRITE_THROUGH)
 
 /** A single metadata element */
 typedef struct grpc_metadata {

data/include/grpc/impl/codegen/port_platform.h

@@ -51,7 +51,9 @@
 /*
  * Defines GRPC_ERROR_IS_ABSEIL_STATUS to use absl::Status for grpc_error_handle
  */
+#ifndef GRPC_ERROR_IS_ABSEIL_STATUS
 // #define GRPC_ERROR_IS_ABSEIL_STATUS 1
+#endif
 
 /* Get windows.h included everywhere (we need it) */
 #if defined(_WIN64) || defined(WIN64) || defined(_WIN32) || defined(WIN32)
@@ -132,9 +134,7 @@
 #if __ANDROID_API__ < 21
 #error "Requires Android API v21 and above"
 #endif
-#if (__ANDROID_API__) >= 23
 #define GPR_SUPPORT_BINDER_TRANSPORT 1
-#endif
 // TODO(apolcyn): re-evaluate support for c-ares
 // on android after upgrading our c-ares dependency.
 // See https://github.com/grpc/grpc/issues/18038.

data/include/grpc/impl/codegen/slice.h

@@ -58,7 +58,10 @@ struct grpc_slice_refcount;
    Multiple grpc_slice values may share a ref count.
 
    If the slice does not have a refcount, it represents an inlined small piece
-   of data that is copied by value. */
+   of data that is copied by value.
+
+   As a special case, a slice can be given refcount == uintptr_t(1), meaning
+   that the slice represents external data that is not refcounted. */
 struct grpc_slice {
   struct grpc_slice_refcount* refcount;
   union grpc_slice_data {

data/include/grpc/slice.h

@@ -69,12 +69,6 @@ GPRAPI grpc_slice grpc_slice_malloc_large(size_t length);
 
 #define GRPC_SLICE_MALLOC(len) grpc_slice_malloc(len)
 
-/** Intern a slice:
-
-   The return value for two invocations of this function with  the same sequence
-   of bytes is a slice which points to the same memory. */
-GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
-
 /** Create a slice by copying a string.
    Does not preserve null terminators.
    Equivalent to:
@@ -129,9 +123,6 @@ GPRAPI grpc_slice grpc_slice_split_head(grpc_slice* s, size_t split);
 
 GPRAPI grpc_slice grpc_empty_slice(void);
 
-GPRAPI uint32_t grpc_slice_default_hash_impl(grpc_slice s);
-GPRAPI int grpc_slice_default_eq_impl(grpc_slice a, grpc_slice b);
-
 GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b);
 
 /** Returns <0 if a < b, ==0 if a == b, >0 if a > b
@@ -151,8 +142,6 @@ GPRAPI int grpc_slice_chr(grpc_slice s, char c);
    if it's not found */
 GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle);
 
-GPRAPI uint32_t grpc_slice_hash(grpc_slice s);
-
 /** Do two slices point at the same memory, with the same length
    If a or b is inlined, actually compares data */
 GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b);