Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Craig Tiller | 6169d5f | 2016-03-31 07:46:18 -0700 | [diff] [blame] | 3 | * Copyright 2015, Google Inc. |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 4 | * All rights reserved. |
| 5 | * |
| 6 | * Redistribution and use in source and binary forms, with or without |
| 7 | * modification, are permitted provided that the following conditions are |
| 8 | * met: |
| 9 | * |
| 10 | * * Redistributions of source code must retain the above copyright |
| 11 | * notice, this list of conditions and the following disclaimer. |
| 12 | * * Redistributions in binary form must reproduce the above |
| 13 | * copyright notice, this list of conditions and the following disclaimer |
| 14 | * in the documentation and/or other materials provided with the |
| 15 | * distribution. |
| 16 | * * Neither the name of Google Inc. nor the names of its |
| 17 | * contributors may be used to endorse or promote products derived from |
| 18 | * this software without specific prior written permission. |
| 19 | * |
| 20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 21 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 22 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 23 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 24 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 25 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 26 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 27 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 28 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 29 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 30 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 31 | * |
| 32 | */ |
| 33 | |
Craig Tiller | 9a4dddd | 2016-03-25 17:08:13 -0700 | [diff] [blame] | 34 | #ifndef GRPC_CORE_LIB_TRANSPORT_METADATA_H |
| 35 | #define GRPC_CORE_LIB_TRANSPORT_METADATA_H |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 36 | |
| 37 | #include <grpc/support/slice.h> |
ctiller | fb93d19 | 2014-12-15 10:40:05 -0800 | [diff] [blame] | 38 | #include <grpc/support/useful.h> |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 39 | |
Mark D. Roth | 07cd9c9 | 2016-06-27 10:14:38 -0700 | [diff] [blame] | 40 | #ifdef __cplusplus |
| 41 | extern "C" { |
| 42 | #endif |
| 43 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 44 | /* This file provides a mechanism for tracking metadata through the grpc stack. |
| 45 | It's not intended for consumption outside of the library. |
| 46 | |
| 47 | Metadata is tracked in the context of a grpc_mdctx. For the time being there |
| 48 | is one of these per-channel, avoiding cross channel interference with memory |
| 49 | use and lock contention. |
| 50 | |
| 51 | The context tracks unique strings (grpc_mdstr) and pairs of strings |
| 52 | (grpc_mdelem). Any of these objects can be checked for equality by comparing |
| 53 | their pointers. These objects are reference counted. |
| 54 | |
| 55 | grpc_mdelem can additionally store a (non-NULL) user data pointer. This |
| 56 | pointer is intended to be used to cache semantic meaning of a metadata |
| 57 | element. For example, an OAuth token may cache the credentials it represents |
| 58 | and the time at which it expires in the mdelem user data. |
| 59 | |
| 60 | Combining this metadata cache and the hpack compression table allows us to |
| 61 | simply lookup complete preparsed objects quickly, incurring a few atomic |
| 62 | ops per metadata element on the fast path. |
| 63 | |
| 64 | grpc_mdelem instances MAY live longer than their refcount implies, and are |
| 65 | garbage collected periodically, meaning cached data can easily outlive a |
Craig Tiller | 70b080d | 2015-11-19 08:04:48 -0800 | [diff] [blame] | 66 | single request. |
| 67 | |
| 68 | STATIC METADATA: in static_metadata.h we declare a set of static metadata. |
| 69 | These mdelems and mdstrs are available via pre-declared code generated macros |
| 70 | and are available to code anywhere between grpc_init() and grpc_shutdown(). |
| 71 | They are not refcounted, but can be passed to _ref and _unref functions |
| 72 | declared here - in which case those functions are effectively no-ops. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 73 | |
| 74 | /* Forward declarations */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 75 | typedef struct grpc_mdstr grpc_mdstr; |
| 76 | typedef struct grpc_mdelem grpc_mdelem; |
| 77 | |
| 78 | /* if changing this, make identical changes in internal_string in metadata.c */ |
| 79 | struct grpc_mdstr { |
Craig Tiller | d41a4a7 | 2016-10-26 16:16:06 -0700 | [diff] [blame^] | 80 | const grpc_slice slice; |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 81 | const uint32_t hash; |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 82 | /* there is a private part to this in metadata.c */ |
| 83 | }; |
| 84 | |
| 85 | /* if changing this, make identical changes in internal_metadata in |
| 86 | metadata.c */ |
| 87 | struct grpc_mdelem { |
| 88 | grpc_mdstr *const key; |
| 89 | grpc_mdstr *const value; |
| 90 | /* there is a private part to this in metadata.c */ |
| 91 | }; |
| 92 | |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 93 | void grpc_test_only_set_metadata_hash_seed(uint32_t seed); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 94 | |
| 95 | /* Constructors for grpc_mdstr instances; take a variety of data types that |
| 96 | clients may have handy */ |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 97 | grpc_mdstr *grpc_mdstr_from_string(const char *str); |
Julien Boeuf | 75c9b6f | 2015-05-29 13:12:12 -0700 | [diff] [blame] | 98 | /* Unrefs the slice. */ |
Craig Tiller | d41a4a7 | 2016-10-26 16:16:06 -0700 | [diff] [blame^] | 99 | grpc_mdstr *grpc_mdstr_from_slice(grpc_slice slice); |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 100 | grpc_mdstr *grpc_mdstr_from_buffer(const uint8_t *str, size_t length); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 101 | |
ctiller | 430c499 | 2014-12-11 09:15:41 -0800 | [diff] [blame] | 102 | /* Returns a borrowed slice from the mdstr with its contents base64 encoded |
| 103 | and huffman compressed */ |
Craig Tiller | d41a4a7 | 2016-10-26 16:16:06 -0700 | [diff] [blame^] | 104 | grpc_slice grpc_mdstr_as_base64_encoded_and_huffman_compressed(grpc_mdstr *str); |
ctiller | 430c499 | 2014-12-11 09:15:41 -0800 | [diff] [blame] | 105 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 106 | /* Constructors for grpc_mdelem instances; take a variety of data types that |
| 107 | clients may have handy */ |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 108 | grpc_mdelem *grpc_mdelem_from_metadata_strings(grpc_mdstr *key, |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 109 | grpc_mdstr *value); |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 110 | grpc_mdelem *grpc_mdelem_from_strings(const char *key, const char *value); |
Julien Boeuf | 75c9b6f | 2015-05-29 13:12:12 -0700 | [diff] [blame] | 111 | /* Unrefs the slices. */ |
Craig Tiller | d41a4a7 | 2016-10-26 16:16:06 -0700 | [diff] [blame^] | 112 | grpc_mdelem *grpc_mdelem_from_slices(grpc_slice key, grpc_slice value); |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 113 | grpc_mdelem *grpc_mdelem_from_string_and_buffer(const char *key, |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 114 | const uint8_t *value, |
Craig Tiller | 4dbdd6a | 2015-09-25 15:12:16 -0700 | [diff] [blame] | 115 | size_t value_length); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 116 | |
yang-g | cb7a802 | 2016-03-30 14:58:53 -0700 | [diff] [blame] | 117 | size_t grpc_mdelem_get_size_in_hpack_table(grpc_mdelem *elem); |
| 118 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 119 | /* Mutator and accessor for grpc_mdelem user data. The destructor function |
| 120 | is used as a type tag and is checked during user_data fetch. */ |
| 121 | void *grpc_mdelem_get_user_data(grpc_mdelem *md, |
| 122 | void (*if_destroy_func)(void *)); |
| 123 | void grpc_mdelem_set_user_data(grpc_mdelem *md, void (*destroy_func)(void *), |
| 124 | void *user_data); |
| 125 | |
| 126 | /* Reference counting */ |
Craig Tiller | a92ebc8 | 2016-04-24 11:43:24 -0700 | [diff] [blame] | 127 | //#define GRPC_METADATA_REFCOUNT_DEBUG |
Craig Tiller | 1a65a23 | 2015-07-06 10:22:32 -0700 | [diff] [blame] | 128 | #ifdef GRPC_METADATA_REFCOUNT_DEBUG |
| 129 | #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s), __FILE__, __LINE__) |
| 130 | #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s), __FILE__, __LINE__) |
| 131 | #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s), __FILE__, __LINE__) |
| 132 | #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s), __FILE__, __LINE__) |
| 133 | grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s, const char *file, int line); |
| 134 | void grpc_mdstr_unref(grpc_mdstr *s, const char *file, int line); |
| 135 | grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md, const char *file, int line); |
| 136 | void grpc_mdelem_unref(grpc_mdelem *md, const char *file, int line); |
| 137 | #else |
| 138 | #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s)) |
| 139 | #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s)) |
| 140 | #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s)) |
| 141 | #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s)) |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 142 | grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s); |
| 143 | void grpc_mdstr_unref(grpc_mdstr *s); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 144 | grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md); |
| 145 | void grpc_mdelem_unref(grpc_mdelem *md); |
Craig Tiller | 1a65a23 | 2015-07-06 10:22:32 -0700 | [diff] [blame] | 146 | #endif |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 147 | |
| 148 | /* Recover a char* from a grpc_mdstr. The returned string is null terminated. |
| 149 | Does not promise that the returned string has no embedded nulls however. */ |
David Garcia Quintas | 331b9c0 | 2016-09-12 18:37:05 -0700 | [diff] [blame] | 150 | const char *grpc_mdstr_as_c_string(const grpc_mdstr *s); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 151 | |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 152 | #define GRPC_MDSTR_LENGTH(s) (GPR_SLICE_LENGTH(s->slice)) |
Mark D. Roth | c2de452 | 2016-04-29 10:25:27 -0700 | [diff] [blame] | 153 | |
| 154 | /* We add 32 bytes of padding as per RFC-7540 section 6.5.2. */ |
Mark D. Roth | 22b338e | 2016-05-04 13:27:56 -0700 | [diff] [blame] | 155 | #define GRPC_MDELEM_LENGTH(e) \ |
| 156 | (GRPC_MDSTR_LENGTH((e)->key) + GRPC_MDSTR_LENGTH((e)->value) + 32) |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 157 | |
Craig Tiller | b96d001 | 2015-05-06 15:33:23 -0700 | [diff] [blame] | 158 | int grpc_mdstr_is_legal_header(grpc_mdstr *s); |
Craig Tiller | 49772e0 | 2015-08-21 08:08:37 -0700 | [diff] [blame] | 159 | int grpc_mdstr_is_legal_nonbin_header(grpc_mdstr *s); |
Craig Tiller | b96d001 | 2015-05-06 15:33:23 -0700 | [diff] [blame] | 160 | int grpc_mdstr_is_bin_suffixed(grpc_mdstr *s); |
| 161 | |
ctiller | fb93d19 | 2014-12-15 10:40:05 -0800 | [diff] [blame] | 162 | #define GRPC_MDSTR_KV_HASH(k_hash, v_hash) (GPR_ROTL((k_hash), 2) ^ (v_hash)) |
| 163 | |
Craig Tiller | 0e72ede | 2015-11-19 07:48:53 -0800 | [diff] [blame] | 164 | void grpc_mdctx_global_init(void); |
| 165 | void grpc_mdctx_global_shutdown(void); |
| 166 | |
Craig Tiller | f82ddc4 | 2016-04-05 17:15:07 -0700 | [diff] [blame] | 167 | /* Implementation provided by chttp2_transport */ |
Craig Tiller | d41a4a7 | 2016-10-26 16:16:06 -0700 | [diff] [blame^] | 168 | extern grpc_slice (*grpc_chttp2_base64_encode_and_huffman_compress)( |
| 169 | grpc_slice input); |
Craig Tiller | f82ddc4 | 2016-04-05 17:15:07 -0700 | [diff] [blame] | 170 | |
Mark D. Roth | 07cd9c9 | 2016-06-27 10:14:38 -0700 | [diff] [blame] | 171 | #ifdef __cplusplus |
| 172 | } |
| 173 | #endif |
| 174 | |
Craig Tiller | 9a4dddd | 2016-03-25 17:08:13 -0700 | [diff] [blame] | 175 | #endif /* GRPC_CORE_LIB_TRANSPORT_METADATA_H */ |