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 | |
| 40 | /* This file provides a mechanism for tracking metadata through the grpc stack. |
| 41 | It's not intended for consumption outside of the library. |
| 42 | |
| 43 | Metadata is tracked in the context of a grpc_mdctx. For the time being there |
| 44 | is one of these per-channel, avoiding cross channel interference with memory |
| 45 | use and lock contention. |
| 46 | |
| 47 | The context tracks unique strings (grpc_mdstr) and pairs of strings |
| 48 | (grpc_mdelem). Any of these objects can be checked for equality by comparing |
| 49 | their pointers. These objects are reference counted. |
| 50 | |
| 51 | grpc_mdelem can additionally store a (non-NULL) user data pointer. This |
| 52 | pointer is intended to be used to cache semantic meaning of a metadata |
| 53 | element. For example, an OAuth token may cache the credentials it represents |
| 54 | and the time at which it expires in the mdelem user data. |
| 55 | |
| 56 | Combining this metadata cache and the hpack compression table allows us to |
| 57 | simply lookup complete preparsed objects quickly, incurring a few atomic |
| 58 | ops per metadata element on the fast path. |
| 59 | |
| 60 | grpc_mdelem instances MAY live longer than their refcount implies, and are |
| 61 | garbage collected periodically, meaning cached data can easily outlive a |
Craig Tiller | 70b080d | 2015-11-19 08:04:48 -0800 | [diff] [blame] | 62 | single request. |
| 63 | |
| 64 | STATIC METADATA: in static_metadata.h we declare a set of static metadata. |
| 65 | These mdelems and mdstrs are available via pre-declared code generated macros |
| 66 | and are available to code anywhere between grpc_init() and grpc_shutdown(). |
| 67 | They are not refcounted, but can be passed to _ref and _unref functions |
| 68 | declared here - in which case those functions are effectively no-ops. */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 69 | |
| 70 | /* Forward declarations */ |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 71 | typedef struct grpc_mdstr grpc_mdstr; |
| 72 | typedef struct grpc_mdelem grpc_mdelem; |
| 73 | |
| 74 | /* if changing this, make identical changes in internal_string in metadata.c */ |
| 75 | struct grpc_mdstr { |
| 76 | const gpr_slice slice; |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 77 | const uint32_t hash; |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 78 | /* there is a private part to this in metadata.c */ |
| 79 | }; |
| 80 | |
| 81 | /* if changing this, make identical changes in internal_metadata in |
| 82 | metadata.c */ |
| 83 | struct grpc_mdelem { |
| 84 | grpc_mdstr *const key; |
| 85 | grpc_mdstr *const value; |
| 86 | /* there is a private part to this in metadata.c */ |
| 87 | }; |
| 88 | |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 89 | void grpc_test_only_set_metadata_hash_seed(uint32_t seed); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 90 | |
| 91 | /* Constructors for grpc_mdstr instances; take a variety of data types that |
| 92 | clients may have handy */ |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 93 | grpc_mdstr *grpc_mdstr_from_string(const char *str); |
Julien Boeuf | 75c9b6f | 2015-05-29 13:12:12 -0700 | [diff] [blame] | 94 | /* Unrefs the slice. */ |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 95 | grpc_mdstr *grpc_mdstr_from_slice(gpr_slice slice); |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 96 | 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] | 97 | |
ctiller | 430c499 | 2014-12-11 09:15:41 -0800 | [diff] [blame] | 98 | /* Returns a borrowed slice from the mdstr with its contents base64 encoded |
| 99 | and huffman compressed */ |
| 100 | gpr_slice grpc_mdstr_as_base64_encoded_and_huffman_compressed(grpc_mdstr *str); |
| 101 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 102 | /* Constructors for grpc_mdelem instances; take a variety of data types that |
| 103 | clients may have handy */ |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 104 | grpc_mdelem *grpc_mdelem_from_metadata_strings(grpc_mdstr *key, |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 105 | grpc_mdstr *value); |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 106 | grpc_mdelem *grpc_mdelem_from_strings(const char *key, const char *value); |
Julien Boeuf | 75c9b6f | 2015-05-29 13:12:12 -0700 | [diff] [blame] | 107 | /* Unrefs the slices. */ |
Craig Tiller | b2b4261 | 2015-11-20 12:02:17 -0800 | [diff] [blame] | 108 | grpc_mdelem *grpc_mdelem_from_slices(gpr_slice key, gpr_slice value); |
| 109 | grpc_mdelem *grpc_mdelem_from_string_and_buffer(const char *key, |
Craig Tiller | 7536af0 | 2015-12-22 13:49:30 -0800 | [diff] [blame] | 110 | const uint8_t *value, |
Craig Tiller | 4dbdd6a | 2015-09-25 15:12:16 -0700 | [diff] [blame] | 111 | size_t value_length); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 112 | |
yang-g | cb7a802 | 2016-03-30 14:58:53 -0700 | [diff] [blame] | 113 | size_t grpc_mdelem_get_size_in_hpack_table(grpc_mdelem *elem); |
| 114 | |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 115 | /* Mutator and accessor for grpc_mdelem user data. The destructor function |
| 116 | is used as a type tag and is checked during user_data fetch. */ |
| 117 | void *grpc_mdelem_get_user_data(grpc_mdelem *md, |
| 118 | void (*if_destroy_func)(void *)); |
| 119 | void grpc_mdelem_set_user_data(grpc_mdelem *md, void (*destroy_func)(void *), |
| 120 | void *user_data); |
| 121 | |
| 122 | /* Reference counting */ |
Craig Tiller | a92ebc8 | 2016-04-24 11:43:24 -0700 | [diff] [blame^] | 123 | //#define GRPC_METADATA_REFCOUNT_DEBUG |
Craig Tiller | 1a65a23 | 2015-07-06 10:22:32 -0700 | [diff] [blame] | 124 | #ifdef GRPC_METADATA_REFCOUNT_DEBUG |
| 125 | #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s), __FILE__, __LINE__) |
| 126 | #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s), __FILE__, __LINE__) |
| 127 | #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s), __FILE__, __LINE__) |
| 128 | #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s), __FILE__, __LINE__) |
| 129 | grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s, const char *file, int line); |
| 130 | void grpc_mdstr_unref(grpc_mdstr *s, const char *file, int line); |
| 131 | grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md, const char *file, int line); |
| 132 | void grpc_mdelem_unref(grpc_mdelem *md, const char *file, int line); |
| 133 | #else |
| 134 | #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s)) |
| 135 | #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s)) |
| 136 | #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s)) |
| 137 | #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s)) |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 138 | grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s); |
| 139 | void grpc_mdstr_unref(grpc_mdstr *s); |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 140 | grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md); |
| 141 | void grpc_mdelem_unref(grpc_mdelem *md); |
Craig Tiller | 1a65a23 | 2015-07-06 10:22:32 -0700 | [diff] [blame] | 142 | #endif |
Nicolas Noble | b7ebd3b | 2014-11-26 16:33:03 -0800 | [diff] [blame] | 143 | |
| 144 | /* Recover a char* from a grpc_mdstr. The returned string is null terminated. |
| 145 | Does not promise that the returned string has no embedded nulls however. */ |
| 146 | const char *grpc_mdstr_as_c_string(grpc_mdstr *s); |
| 147 | |
murgatroid99 | c3910ca | 2016-01-06 13:14:23 -0800 | [diff] [blame] | 148 | #define GRPC_MDSTR_LENGTH(s) (GPR_SLICE_LENGTH(s->slice)) |
| 149 | |
Craig Tiller | b96d001 | 2015-05-06 15:33:23 -0700 | [diff] [blame] | 150 | int grpc_mdstr_is_legal_header(grpc_mdstr *s); |
Craig Tiller | 49772e0 | 2015-08-21 08:08:37 -0700 | [diff] [blame] | 151 | int grpc_mdstr_is_legal_nonbin_header(grpc_mdstr *s); |
Craig Tiller | b96d001 | 2015-05-06 15:33:23 -0700 | [diff] [blame] | 152 | int grpc_mdstr_is_bin_suffixed(grpc_mdstr *s); |
| 153 | |
ctiller | fb93d19 | 2014-12-15 10:40:05 -0800 | [diff] [blame] | 154 | #define GRPC_MDSTR_KV_HASH(k_hash, v_hash) (GPR_ROTL((k_hash), 2) ^ (v_hash)) |
| 155 | |
Craig Tiller | 0e72ede | 2015-11-19 07:48:53 -0800 | [diff] [blame] | 156 | void grpc_mdctx_global_init(void); |
| 157 | void grpc_mdctx_global_shutdown(void); |
| 158 | |
Craig Tiller | f82ddc4 | 2016-04-05 17:15:07 -0700 | [diff] [blame] | 159 | /* Implementation provided by chttp2_transport */ |
| 160 | extern gpr_slice (*grpc_chttp2_base64_encode_and_huffman_compress)( |
| 161 | gpr_slice input); |
| 162 | |
Craig Tiller | 9a4dddd | 2016-03-25 17:08:13 -0700 | [diff] [blame] | 163 | #endif /* GRPC_CORE_LIB_TRANSPORT_METADATA_H */ |