Line data Source code
1 : #pragma once
2 :
3 : #include <cstdint>
4 : #include <functional>
5 : #include <memory>
6 : #include <string>
7 :
8 : #include "envoy/access_log/access_log.h"
9 : #include "envoy/buffer/buffer.h"
10 : #include "envoy/common/scope_tracker.h"
11 : #include "envoy/event/dispatcher.h"
12 : #include "envoy/grpc/status.h"
13 : #include "envoy/http/codec.h"
14 : #include "envoy/http/filter_factory.h"
15 : #include "envoy/http/header_map.h"
16 : #include "envoy/matcher/matcher.h"
17 : #include "envoy/router/router.h"
18 : #include "envoy/ssl/connection.h"
19 : #include "envoy/tracing/tracer.h"
20 : #include "envoy/upstream/load_balancer.h"
21 : #include "envoy/upstream/upstream.h"
22 :
23 : #include "source/common/common/scope_tracked_object_stack.h"
24 :
25 : #include "absl/types/optional.h"
26 :
27 : namespace Envoy {
28 : namespace Http {
29 :
30 : /**
31 : * Return codes for encode/decode headers filter invocations. The connection manager bases further
32 : * filter invocations on the return code of the previous filter.
33 : */
34 : enum class FilterHeadersStatus {
35 : // Continue filter chain iteration.
36 : Continue,
37 : // Do not iterate for headers on any of the remaining filters in the chain.
38 : //
39 : // Returning FilterDataStatus::Continue from decodeData()/encodeData() or calling
40 : // continueDecoding()/continueEncoding() MUST be called if continued filter iteration is desired.
41 : //
42 : // Note that if a local reply was sent, no further iteration for headers as well as data and
43 : // trailers for the current filter and the filters following will happen. A local reply can be
44 : // triggered via sendLocalReply() or encodeHeaders().
45 : StopIteration,
46 : // Continue headers iteration to remaining filters, but delay ending the stream. This status MUST
47 : // NOT be returned when end_stream is already set to false.
48 : //
49 : // Used when a filter wants to add a body to a headers-only request/response, but this body is not
50 : // readily available. Delaying end_stream allows the filter to add the body once it's available
51 : // without stopping headers iteration.
52 : //
53 : // The filter is responsible to continue the stream by providing a body through calling
54 : // injectDecodedDataToFilterChain()/injectEncodedDataToFilterChain(), possibly multiple times
55 : // if the body needs to be divided into several chunks. The filter may need to handle
56 : // watermark events when injecting a body, see:
57 : // https://github.com/envoyproxy/envoy/blob/main/source/docs/flow_control.md.
58 : //
59 : // The last call to inject data MUST have end_stream set to true to conclude the stream.
60 : // If the filter cannot provide a body the stream should be reset.
61 : //
62 : // Adding a body through calling addDecodedData()/addEncodedData() then
63 : // continueDecoding()/continueEncoding() is currently NOT supported and causes an assert failure.
64 : //
65 : // Adding trailers in this scenario is currently NOT supported.
66 : //
67 : // The filter MUST NOT attempt to continue the stream without providing a body using
68 : // continueDecoding()/continueEncoding().
69 : //
70 : // TODO(yosrym93): Support adding a body in this case by calling addDecodedData()/addEncodedData()
71 : // then continueDecoding()/continueEncoding(). To support this a new FilterManager::IterationState
72 : // needs to be added and set when a filter returns this status in
73 : // FilterManager::decodeHeaders/FilterManager::encodeHeaders()
74 : // Currently, when a filter returns this, the IterationState is Continue. This causes ASSERTs in
75 : // FilterManager::commonContinue() to fail when continueDecoding()/continueEncoding() is called;
76 : // due to trying to continue iteration when the IterationState is already Continue.
77 : // In this case, a different ASSERT will be needed to make sure the filter does not try to
78 : // continue without adding a body first.
79 : //
80 : // TODO(yosrym93): Support adding trailers in this case by implementing new functions to inject
81 : // trailers, similar to the inject data functions.
82 : ContinueAndDontEndStream,
83 : // Do not iterate for headers as well as data and trailers for the current filter and the filters
84 : // following, and buffer body data for later dispatching. ContinueDecoding() MUST
85 : // be called if continued filter iteration is desired.
86 : //
87 : // Used when a filter wants to stop iteration on data and trailers while waiting for headers'
88 : // iteration to resume.
89 : //
90 : // If buffering the request causes buffered data to exceed the configured buffer limit, a 413 will
91 : // be sent to the user. On the response path exceeding buffer limits will result in a 500.
92 : //
93 : // TODO(soya3129): stop metadata parsing when StopAllIterationAndBuffer is set.
94 : StopAllIterationAndBuffer,
95 : // Do not iterate for headers as well as data and trailers for the current filter and the filters
96 : // following, and buffer body data for later dispatching. continueDecoding() MUST
97 : // be called if continued filter iteration is desired.
98 : //
99 : // Used when a filter wants to stop iteration on data and trailers while waiting for headers'
100 : // iteration to resume.
101 : //
102 : // This will cause the flow of incoming data to cease until continueDecoding() function is called.
103 : //
104 : // TODO(soya3129): stop metadata parsing when StopAllIterationAndWatermark is set.
105 : StopAllIterationAndWatermark,
106 : };
107 :
108 : /**
109 : * Return codes for encode on informative headers filter invocations.
110 : */
111 : enum class Filter1xxHeadersStatus {
112 : // Continue filter chain iteration.
113 : Continue,
114 : // Do not iterate for informative headers on any of the remaining filters in the chain.
115 : //
116 : // Returning FilterDataStatus::Continue from encodeData() or calling
117 : // continueEncoding() MUST be called if continued filter iteration is desired.
118 : StopIteration
119 : };
120 :
121 : /**
122 : * Return codes for encode/decode data filter invocations. The connection manager bases further
123 : * filter invocations on the return code of the previous filter.
124 : */
125 : enum class FilterDataStatus {
126 : // Continue filter chain iteration. If headers have not yet been sent to the next filter, they
127 : // will be sent first via decodeHeaders()/encodeHeaders(). If data has previously been buffered,
128 : // the data in this callback will be added to the buffer before the entirety is sent to the next
129 : // filter.
130 : Continue,
131 : // Do not iterate to any of the remaining filters in the chain, and buffer body data for later
132 : // dispatching. Returning FilterDataStatus::Continue from decodeData()/encodeData() or calling
133 : // continueDecoding()/continueEncoding() MUST be called if continued filter iteration is desired.
134 : //
135 : // This should be called by filters which must parse a larger block of the incoming data before
136 : // continuing processing and so can not push back on streaming data via watermarks.
137 : //
138 : // If buffering the request causes buffered data to exceed the configured buffer limit, a 413 will
139 : // be sent to the user. On the response path exceeding buffer limits will result in a 500.
140 : StopIterationAndBuffer,
141 : // Do not iterate to any of the remaining filters in the chain, and buffer body data for later
142 : // dispatching. Returning FilterDataStatus::Continue from decodeData()/encodeData() or calling
143 : // continueDecoding()/continueEncoding() MUST be called if continued filter iteration is desired.
144 : //
145 : // This will cause the flow of incoming data to cease until one of the continue.*() functions is
146 : // called.
147 : //
148 : // This should be returned by filters which can nominally stream data but have a transient back-up
149 : // such as the configured delay of the fault filter, or if the router filter is still fetching an
150 : // upstream connection.
151 : StopIterationAndWatermark,
152 : // Do not iterate to any of the remaining filters in the chain, but do not buffer any of the
153 : // body data for later dispatching. Returning FilterDataStatus::Continue from
154 : // decodeData()/encodeData() or calling continueDecoding()/continueEncoding() MUST be called if
155 : // continued filter iteration is desired.
156 : //
157 : // Note that if a local reply was sent, no further iteration for either data or trailers
158 : // for the current filter and the filters following will happen. A local reply can be
159 : // triggered via sendLocalReply() or encodeHeaders().
160 : StopIterationNoBuffer
161 : };
162 :
163 : /**
164 : * Return codes for encode/decode trailers filter invocations. The connection manager bases further
165 : * filter invocations on the return code of the previous filter.
166 : */
167 : enum class FilterTrailersStatus {
168 : // Continue filter chain iteration.
169 : Continue,
170 : // Do not iterate to any of the remaining filters in the chain. Calling
171 : // continueDecoding()/continueEncoding() MUST be called if continued filter iteration is desired.
172 : StopIteration
173 : };
174 :
175 : /**
176 : * Return codes for encode metadata filter invocations. Metadata currently can not stop filter
177 : * iteration except in the case of local replies.
178 : */
179 : enum class FilterMetadataStatus {
180 : // Continue filter chain iteration for metadata only. Does not unblock returns of StopIteration*
181 : // from (decode|encode)(Headers|Data).
182 : Continue,
183 :
184 : // Continue filter chain iteration. If headers have not yet been sent to the next filter, they
185 : // will be sent first via (decode|encode)Headers().
186 : ContinueAll,
187 :
188 : // Stops iteration of the entire filter chain. Only to be used in the case of sending a local
189 : // reply from (decode|encode)Metadata.
190 : StopIterationForLocalReply,
191 : };
192 :
193 : /**
194 : * Return codes for onLocalReply filter invocations.
195 : */
196 : enum class LocalErrorStatus {
197 : // Continue sending the local reply after onLocalReply has been sent to all filters.
198 : Continue,
199 :
200 : // Continue sending onLocalReply to all filters, but reset the stream once all filters have been
201 : // informed rather than sending the local reply.
202 : ContinueAndResetStream,
203 : };
204 :
205 : // These are events that upstream HTTP filters can register for, via the addUpstreamCallbacks
206 : // function.
207 : class UpstreamCallbacks {
208 : public:
209 251 : virtual ~UpstreamCallbacks() = default;
210 :
211 : // Called when the upstream connection is established and
212 : // UpstreamStreamFilterCallbacks::upstream should be available.
213 : //
214 : // This indicates that data may begin flowing upstream.
215 : virtual void onUpstreamConnectionEstablished() PURE;
216 : };
217 :
218 : // These are filter callbacks specific to upstream HTTP filters, accessible via
219 : // StreamFilterCallbacks::upstreamCallbacks()
220 : class UpstreamStreamFilterCallbacks {
221 : public:
222 251 : virtual ~UpstreamStreamFilterCallbacks() = default;
223 :
224 : // Returns a handle to the upstream stream's stream info.
225 : virtual StreamInfo::StreamInfo& upstreamStreamInfo() PURE;
226 :
227 : // Returns a handle to the generic upstream.
228 : virtual OptRef<Router::GenericUpstream> upstream() PURE;
229 :
230 : // Dumps state for the upstream request.
231 : virtual void dumpState(std::ostream& os, int indent_level = 0) const PURE;
232 :
233 : // Setters and getters to determine if sending body payload is paused on
234 : // confirmation of a CONNECT upgrade. These should only be used by the upstream codec filter.
235 : // TODO(alyssawilk) after deprecating the classic path, move this logic to the
236 : // upstream codec filter and remove these APIs
237 : virtual bool pausedForConnect() const PURE;
238 : virtual void setPausedForConnect(bool value) PURE;
239 :
240 : // Return the upstreamStreamOptions for this stream.
241 : virtual const Http::ConnectionPool::Instance::StreamOptions& upstreamStreamOptions() const PURE;
242 :
243 : // Adds the supplied UpstreamCallbacks to the list of callbacks to be called
244 : // as various upstream events occur. Callbacks should persist for the lifetime
245 : // of the upstream stream.
246 : virtual void addUpstreamCallbacks(UpstreamCallbacks& callbacks) PURE;
247 :
248 : // This should only be called by the UpstreamCodecFilter, and is used to let the
249 : // UpstreamCodecFilter supply the interface used by the GenericUpstream to receive
250 : // response data from the upstream stream once it is established.
251 : virtual void
252 : setUpstreamToDownstream(Router::UpstreamToDownstream& upstream_to_downstream_interface) PURE;
253 : };
254 :
255 : /**
256 : * RouteConfigUpdatedCallback is used to notify an OnDemandRouteUpdate filter about completion of a
257 : * RouteConfig update. The filter (and the associated ActiveStream) where the original on-demand
258 : * request was originated can be destroyed before a response to an on-demand update request is
259 : * received and updates are propagated. To handle this:
260 : *
261 : * OnDemandRouteUpdate filter instance holds a RouteConfigUpdatedCallbackSharedPtr to a callback.
262 : * Envoy::Router::RdsRouteConfigProviderImpl holds a weak pointer to the RouteConfigUpdatedCallback
263 : * above in an Envoy::Router::UpdateOnDemandCallback struct
264 : *
265 : * In RdsRouteConfigProviderImpl::onConfigUpdate(), before invoking the callback, a check is made to
266 : * verify if the callback is still available.
267 : */
268 : using RouteConfigUpdatedCallback = std::function<void(bool)>;
269 : using RouteConfigUpdatedCallbackSharedPtr = std::shared_ptr<RouteConfigUpdatedCallback>;
270 :
271 : class DownstreamStreamFilterCallbacks {
272 : public:
273 699 : virtual ~DownstreamStreamFilterCallbacks() = default;
274 :
275 : /**
276 : * Sets the cached route for the current request to the passed-in RouteConstSharedPtr parameter.
277 : *
278 : * Similar to route(const Router::RouteCallback& cb), this route that is set will be
279 : * overridden by clearRouteCache() in subsequent filters. Usage is intended for filters at the end
280 : * of the filter chain.
281 : *
282 : * NOTE: Passing nullptr in as the route parameter is equivalent to route resolution being
283 : * attempted and failing to find a route. An example of when this happens is when
284 : * RouteConstSharedPtr route(const RouteCallback& cb, const Http::RequestHeaderMap& headers, const
285 : * StreamInfo::StreamInfo& stream_info, uint64_t random_value) returns nullptr during a
286 : * refreshCachedRoute. It is important to note that setRoute(nullptr) is different from a
287 : * clearRouteCache(), because clearRouteCache() wants route resolution to be attempted again.
288 : * clearRouteCache() achieves this by setting cached_route_ and cached_cluster_info_ to
289 : * absl::optional ptrs instead of null ptrs.
290 : */
291 : virtual void setRoute(Router::RouteConstSharedPtr route) PURE;
292 :
293 : /**
294 : * Invokes callback with a matched route, callback can choose to accept this route by returning
295 : * Router::RouteMatchStatus::Accept or continue route match from last matched route by returning
296 : * Router::RouteMatchStatus::Continue, if there are more routes available.
297 : *
298 : * Returns route accepted by the callback or nullptr if no match found or none of route is
299 : * accepted by the callback.
300 : *
301 : * NOTE: clearRouteCache() must be called before invoking this method otherwise cached route will
302 : * be returned directly to the caller and the callback will not be invoked.
303 : *
304 : * Currently a route callback's decision is overridden by clearRouteCache() / route() call in the
305 : * subsequent filters. We may want to persist callbacks so they always participate in later route
306 : * resolution or make it an independent entity like filters that gets called on route resolution.
307 : */
308 : virtual Router::RouteConstSharedPtr route(const Router::RouteCallback& cb) PURE;
309 :
310 : /**
311 : * Clears the route cache for the current request. This must be called when a filter has modified
312 : * the headers in a way that would affect routing.
313 : */
314 : virtual void clearRouteCache() PURE;
315 :
316 : /**
317 : * Schedules a request for a RouteConfiguration update from the management server.
318 : * @param route_config_updated_cb callback to be called when the configuration update has been
319 : * propagated to the worker thread.
320 : */
321 : virtual void
322 : requestRouteConfigUpdate(RouteConfigUpdatedCallbackSharedPtr route_config_updated_cb) PURE;
323 : };
324 :
325 : /**
326 : * The stream filter callbacks are passed to all filters to use for writing response data and
327 : * interacting with the underlying stream in general.
328 : */
329 : class StreamFilterCallbacks {
330 : public:
331 1206 : virtual ~StreamFilterCallbacks() = default;
332 :
333 : /**
334 : * @return OptRef<const Network::Connection> the downstream connection, or nullptr if there is
335 : * none.
336 : */
337 : virtual OptRef<const Network::Connection> connection() PURE;
338 :
339 : /**
340 : * @return Event::Dispatcher& the thread local dispatcher for allocating timers, etc.
341 : */
342 : virtual Event::Dispatcher& dispatcher() PURE;
343 :
344 : /**
345 : * Reset the underlying stream.
346 : */
347 : virtual void
348 : resetStream(Http::StreamResetReason reset_reason = Http::StreamResetReason::LocalReset,
349 : absl::string_view transport_failure_reason = "") PURE;
350 :
351 : /**
352 : * Returns the route for the current request. The assumption is that the implementation can do
353 : * caching where applicable to avoid multiple lookups. If a filter has modified the headers in
354 : * a way that affects routing, clearRouteCache() must be called to clear the cache.
355 : */
356 : virtual Router::RouteConstSharedPtr route() PURE;
357 :
358 : /**
359 : * Returns the clusterInfo for the cached route.
360 : * This method is to avoid multiple look ups in the filter chain, it also provides a consistent
361 : * view of clusterInfo after a route is picked/repicked.
362 : * NOTE: Cached clusterInfo and route will be updated the same time.
363 : */
364 : virtual Upstream::ClusterInfoConstSharedPtr clusterInfo() PURE;
365 :
366 : /**
367 : * @return uint64_t the ID of the originating stream for logging purposes.
368 : */
369 : virtual uint64_t streamId() const PURE;
370 :
371 : /**
372 : * @return streamInfo for logging purposes. Individual filter may add specific information to be
373 : * put into the access log.
374 : */
375 : virtual StreamInfo::StreamInfo& streamInfo() PURE;
376 :
377 : /**
378 : * @return span context used for tracing purposes. Individual filters may add or modify
379 : * information in the span context.
380 : */
381 : virtual Tracing::Span& activeSpan() PURE;
382 :
383 : /**
384 : * @return tracing configuration if present.
385 : */
386 : virtual OptRef<const Tracing::Config> tracingConfig() const PURE;
387 :
388 : /**
389 : * @return the ScopeTrackedObject for this stream.
390 : */
391 : virtual const ScopeTrackedObject& scope() PURE;
392 :
393 : /**
394 : * Should be used when we continue processing a request or response by invoking a filter directly
395 : * from an asynchronous callback to restore crash context. If not explicitly used by the filter
396 : * itself, this gets invoked in ActiveStreamFilterBase::commonContinue().
397 : *
398 : * @param tracked_object_stack ScopeTrackedObjectStack where relevant ScopeTrackedObjects will be
399 : * added to.
400 : */
401 : virtual void restoreContextOnContinue(ScopeTrackedObjectStack& tracked_object_stack) PURE;
402 :
403 : /**
404 : * Called when filter activity indicates that the stream idle timeout should be reset.
405 : */
406 : virtual void resetIdleTimer() PURE;
407 :
408 : /**
409 : * This is a helper to get the route's per-filter config if it exists, otherwise the virtual
410 : * host's. Or nullptr if none of them exist.
411 : */
412 : virtual const Router::RouteSpecificFilterConfig* mostSpecificPerFilterConfig() const PURE;
413 :
414 : /**
415 : * Find all the available per route filter configs, invoking the callback with each config (if
416 : * it is present). Iteration of the configs is in order of specificity. That means that the
417 : * callback will be called first for a config on a Virtual host, then a route, and finally a route
418 : * entry (weighted cluster). If a config is not present, the callback will not be invoked.
419 : */
420 : virtual void traversePerFilterConfig(
421 : std::function<void(const Router::RouteSpecificFilterConfig&)> cb) const PURE;
422 :
423 : /**
424 : * Return the HTTP/1 stream encoder options if applicable. If the stream is not HTTP/1 returns
425 : * absl::nullopt.
426 : */
427 : virtual Http1StreamEncoderOptionsOptRef http1StreamEncoderOptions() PURE;
428 :
429 : /**
430 : * Return a handle to the upstream callbacks. This is valid for upstream HTTP filters, and nullopt
431 : * for downstream HTTP filters.
432 : */
433 : virtual OptRef<UpstreamStreamFilterCallbacks> upstreamCallbacks() PURE;
434 :
435 : /**
436 : * Return a handle to the downstream callbacks. This is valid for downstream HTTP filters, and
437 : * nullopt for upstream HTTP filters.
438 : */
439 : virtual OptRef<DownstreamStreamFilterCallbacks> downstreamCallbacks() PURE;
440 :
441 : /**
442 : * @return absl::string_view the name of the filter as configured in the filter chain.
443 : */
444 : virtual absl::string_view filterConfigName() const PURE;
445 :
446 : /**
447 : * The downstream request headers if present.
448 : */
449 : virtual RequestHeaderMapOptRef requestHeaders() PURE;
450 :
451 : /**
452 : * The downstream request trailers if present.
453 : */
454 : virtual RequestTrailerMapOptRef requestTrailers() PURE;
455 :
456 : /**
457 : * Retrieves a pointer to the continue headers if present.
458 : */
459 : virtual ResponseHeaderMapOptRef informationalHeaders() PURE;
460 :
461 : /**
462 : * Retrieves a pointer to the response headers if present.
463 : * Note that response headers might be set multiple times (e.g. if a local reply is issued after
464 : * headers have been received but before headers have been encoded), so it is not safe in general
465 : * to assume that any set of headers will be valid for the duration of the stream.
466 : */
467 : virtual ResponseHeaderMapOptRef responseHeaders() PURE;
468 :
469 : /**
470 : * Retrieves a pointer to the last response trailers if present.
471 : * Note that response headers might be set multiple times (e.g. if a local reply is issued after
472 : * headers have been received but before headers have been encoded), so it is not safe in general
473 : * to assume that any set of headers will be valid for the duration of the stream.
474 : */
475 : virtual ResponseTrailerMapOptRef responseTrailers() PURE;
476 : };
477 :
478 : class DecoderFilterWatermarkCallbacks {
479 : public:
480 1009 : virtual ~DecoderFilterWatermarkCallbacks() = default;
481 :
482 : /**
483 : * Called when the buffer for a decoder filter or any buffers the filter sends data to go over
484 : * their high watermark.
485 : *
486 : * In the case of a filter such as the router filter, which spills into multiple buffers (codec,
487 : * connection etc.) this may be called multiple times. Any such filter is responsible for calling
488 : * the low watermark callbacks an equal number of times as the respective buffers are drained.
489 : */
490 : virtual void onDecoderFilterAboveWriteBufferHighWatermark() PURE;
491 :
492 : /**
493 : * Called when a decoder filter or any buffers the filter sends data to go from over its high
494 : * watermark to under its low watermark.
495 : */
496 : virtual void onDecoderFilterBelowWriteBufferLowWatermark() PURE;
497 : };
498 : /**
499 : * Stream decoder filter callbacks add additional callbacks that allow a
500 : * decoding filter to restart decoding if they decide to hold data (e.g. for
501 : * buffering or rate limiting).
502 : */
503 : class StreamDecoderFilterCallbacks : public virtual StreamFilterCallbacks,
504 : public virtual DecoderFilterWatermarkCallbacks {
505 : public:
506 : /**
507 : * Continue iterating through the filter chain with buffered headers and body data. This routine
508 : * can only be called if the filter has previously returned StopIteration from decodeHeaders()
509 : * AND one of StopIterationAndBuffer, StopIterationAndWatermark, or StopIterationNoBuffer
510 : * from each previous call to decodeData().
511 : *
512 : * The connection manager will dispatch headers and any buffered body data to the
513 : * next filter in the chain. Further note that if the request is not complete, this filter will
514 : * still receive decodeData() calls and must return an appropriate status code depending on what
515 : * the filter needs to do.
516 : */
517 : virtual void continueDecoding() PURE;
518 :
519 : /**
520 : * @return const Buffer::Instance* the currently buffered data as buffered by this filter or
521 : * previous ones in the filter chain. May be nullptr if nothing has been buffered yet.
522 : */
523 : virtual const Buffer::Instance* decodingBuffer() PURE;
524 :
525 : /**
526 : * Allows modifying the decoding buffer. May only be called before any data has been continued
527 : * past the calling filter.
528 : */
529 : virtual void modifyDecodingBuffer(std::function<void(Buffer::Instance&)> callback) PURE;
530 :
531 : /**
532 : * Add buffered body data. This method is used in advanced cases where returning
533 : * StopIterationAndBuffer from decodeData() is not sufficient.
534 : *
535 : * 1) If a headers only request needs to be turned into a request with a body, this method can
536 : * be called to add body in the decodeHeaders() callback. Subsequent filters will receive
537 : * decodeHeaders(..., false) followed by decodeData(..., true). This works both in the direct
538 : * iteration as well as the continuation case.
539 : *
540 : * 2) If a filter is going to look at all buffered data from within a data callback with end
541 : * stream set, this method can be called to immediately buffer the data. This avoids having
542 : * to deal with the existing buffered data and the data from the current callback.
543 : *
544 : * 3) If additional buffered body data needs to be added by a filter before continuation of data
545 : * to further filters (outside of callback context).
546 : *
547 : * 4) If additional data needs to be added in the decodeTrailers() callback, this method can be
548 : * called in the context of the callback. All further filters will receive decodeData(..., false)
549 : * followed by decodeTrailers(). However if the iteration is stopped, the added data will
550 : * buffered, so that the further filters will not receive decodeData() before decodeHeaders().
551 : *
552 : * It is an error to call this method in any other case.
553 : *
554 : * See also injectDecodedDataToFilterChain() for a different way of passing data to further
555 : * filters and also how the two methods are different.
556 : *
557 : * @param data Buffer::Instance supplies the data to be decoded.
558 : * @param streaming_filter boolean supplies if this filter streams data or buffers the full body.
559 : */
560 : virtual void addDecodedData(Buffer::Instance& data, bool streaming_filter) PURE;
561 :
562 : /**
563 : * Decode data directly to subsequent filters in the filter chain. This method is used in
564 : * advanced cases in which a filter needs full control over how subsequent filters view data,
565 : * and does not want to make use of HTTP connection manager buffering. Using this method allows
566 : * a filter to buffer data (or not) and then periodically inject data to subsequent filters,
567 : * indicating end_stream at an appropriate time. This can be used to implement rate limiting,
568 : * periodic data emission, etc.
569 : *
570 : * This method should only be called outside of callback context. I.e., do not call this method
571 : * from within a filter's decodeData() call.
572 : *
573 : * When using this callback, filters should generally only return
574 : * FilterDataStatus::StopIterationNoBuffer from their decodeData() call, since use of this method
575 : * indicates that a filter does not wish to participate in standard HTTP connection manager
576 : * buffering and continuation and will perform any necessary buffering and continuation on its
577 : * own.
578 : *
579 : * This callback is different from addDecodedData() in that the specified data and end_stream
580 : * status will be propagated directly to further filters in the filter chain. This is different
581 : * from addDecodedData() where data is added to the HTTP connection manager's buffered data with
582 : * the assumption that standard HTTP connection manager buffering and continuation are being used.
583 : */
584 : virtual void injectDecodedDataToFilterChain(Buffer::Instance& data, bool end_stream) PURE;
585 :
586 : /**
587 : * Adds decoded trailers. May only be called in decodeData when end_stream is set to true.
588 : * If called in any other context, an assertion will be triggered.
589 : *
590 : * When called in decodeData, the trailers map will be initialized to an empty map and returned by
591 : * reference. Calling this function more than once is invalid.
592 : *
593 : * @return a reference to the newly created trailers map.
594 : */
595 : virtual RequestTrailerMap& addDecodedTrailers() PURE;
596 :
597 : /**
598 : * Attempts to create a locally generated response using the provided response_code and body_text
599 : * parameters. If the request was a gRPC request the local reply will be encoded as a gRPC
600 : * response with a 200 HTTP response code and grpc-status and grpc-message headers mapped from the
601 : * provided parameters.
602 : *
603 : * If a response has already started (e.g. if the router calls sendLocalReply after encoding
604 : * headers) this will either ship the reply directly to the downstream codec, or reset the stream.
605 : *
606 : * @param response_code supplies the HTTP response code.
607 : * @param body_text supplies the optional body text which is sent using the text/plain content
608 : * type, or encoded in the grpc-message header.
609 : * @param modify_headers supplies an optional callback function that can modify the
610 : * response headers.
611 : * @param grpc_status the gRPC status code to override the httpToGrpcStatus mapping with.
612 : * @param details a string detailing why this local reply was sent.
613 : */
614 : virtual void sendLocalReply(Code response_code, absl::string_view body_text,
615 : std::function<void(ResponseHeaderMap& headers)> modify_headers,
616 : const absl::optional<Grpc::Status::GrpcStatus> grpc_status,
617 : absl::string_view details) PURE;
618 :
619 : /**
620 : * Adds decoded metadata. This function can only be called in
621 : * StreamDecoderFilter::decodeHeaders/Data/Trailers(). Do not call in
622 : * StreamDecoderFilter::decodeMetadata().
623 : *
624 : * @return a reference to metadata map vector, where new metadata map can be added.
625 : */
626 : virtual MetadataMapVector& addDecodedMetadata() PURE;
627 :
628 : /**
629 : * Called with 1xx headers to be encoded.
630 : *
631 : * Currently supported codes for this function include 100.
632 : *
633 : * This is not folded into encodeHeaders because most Envoy users and filters will not be proxying
634 : * 1xx headers and with it split out, can ignore the complexity of multiple encodeHeaders calls.
635 : *
636 : * This is currently only called once per request but implementations should
637 : * handle multiple calls as multiple 1xx headers are legal.
638 : *
639 : * @param headers supplies the headers to be encoded.
640 : */
641 : virtual void encode1xxHeaders(ResponseHeaderMapPtr&& headers) PURE;
642 :
643 : /**
644 : * Called with headers to be encoded, optionally indicating end of stream.
645 : *
646 : * The connection manager inspects certain pseudo headers that are not actually sent downstream.
647 : * - See source/common/http/headers.h
648 : *
649 : * The only 1xx that may be provided to encodeHeaders() is a 101 upgrade, which will be the final
650 : * encodeHeaders() for a response.
651 : *
652 : * @param headers supplies the headers to be encoded.
653 : * @param end_stream supplies whether this is a header only request/response.
654 : * @param details supplies the details of why this response was sent.
655 : */
656 : virtual void encodeHeaders(ResponseHeaderMapPtr&& headers, bool end_stream,
657 : absl::string_view details) PURE;
658 :
659 : /**
660 : * Called with data to be encoded, optionally indicating end of stream.
661 : * @param data supplies the data to be encoded.
662 : * @param end_stream supplies whether this is the last data frame.
663 : */
664 : virtual void encodeData(Buffer::Instance& data, bool end_stream) PURE;
665 :
666 : /**
667 : * Called with trailers to be encoded. This implicitly ends the stream.
668 : * @param trailers supplies the trailers to encode.
669 : */
670 : virtual void encodeTrailers(ResponseTrailerMapPtr&& trailers) PURE;
671 :
672 : /**
673 : * Called with metadata to be encoded.
674 : *
675 : * @param metadata_map supplies the unique_ptr of the metadata to be encoded.
676 : */
677 : virtual void encodeMetadata(MetadataMapPtr&& metadata_map) PURE;
678 :
679 : /**
680 : * This routine can be called by a filter to subscribe to watermark events on the downstream
681 : * stream and downstream connection.
682 : *
683 : * Immediately after subscribing, the filter will get a high watermark callback for each
684 : * outstanding backed up buffer.
685 : */
686 : virtual void addDownstreamWatermarkCallbacks(DownstreamWatermarkCallbacks& callbacks) PURE;
687 :
688 : /**
689 : * This routine can be called by a filter to stop subscribing to watermark events on the
690 : * downstream stream and downstream connection.
691 : *
692 : * It is not safe to call this from under the stack of a DownstreamWatermarkCallbacks callback.
693 : */
694 : virtual void removeDownstreamWatermarkCallbacks(DownstreamWatermarkCallbacks& callbacks) PURE;
695 :
696 : /**
697 : * This routine may be called to change the buffer limit for decoder filters.
698 : *
699 : * It is recommended (but not required) that filters calling this function should
700 : * generally only perform increases to the buffer limit, to avoid potentially
701 : * conflicting with the buffer requirements of other filters in the chain, i.e.
702 : *
703 : * if (desired_limit > decoderBufferLimit()) {setDecoderBufferLimit(desired_limit);}
704 : *
705 : * @param limit supplies the desired buffer limit.
706 : */
707 : virtual void setDecoderBufferLimit(uint32_t limit) PURE;
708 :
709 : /**
710 : * This routine returns the current buffer limit for decoder filters. Filters should abide by
711 : * this limit or change it via setDecoderBufferLimit.
712 : * A buffer limit of 0 bytes indicates no limits are applied.
713 : *
714 : * @return the buffer limit the filter should apply.
715 : */
716 : virtual uint32_t decoderBufferLimit() PURE;
717 :
718 : /**
719 : * @return the account, if any, used by this stream.
720 : */
721 : virtual Buffer::BufferMemoryAccountSharedPtr account() const PURE;
722 :
723 : /**
724 : * Takes a stream, and acts as if the headers are newly arrived.
725 : * On success, this will result in a creating a new filter chain and likely
726 : * upstream request associated with the original downstream stream. On
727 : * failure, if the preconditions outlined below are not met, the caller is
728 : * responsible for handling or terminating the original stream.
729 : *
730 : * This is currently limited to
731 : * - streams which are completely read
732 : * - streams which do not have a request body.
733 : *
734 : * Note that HttpConnectionManager sanitization will *not* be performed on the
735 : * recreated stream, as it is assumed that sanitization has already been done.
736 : *
737 : * @param original_response_headers Headers used for logging in the access logs and for charging
738 : * stats. Ignored if null.
739 : */
740 : virtual bool recreateStream(const ResponseHeaderMap* original_response_headers) PURE;
741 :
742 : /**
743 : * Adds socket options to be applied to any connections used for upstream requests. Note that
744 : * unique values for the options will likely lead to many connection pools being created. The
745 : * added options are appended to any previously added.
746 : *
747 : * @param options The options to be added.
748 : */
749 : virtual void addUpstreamSocketOptions(const Network::Socket::OptionsSharedPtr& options) PURE;
750 :
751 : /**
752 : * @return The socket options to be applied to the upstream request.
753 : */
754 : virtual Network::Socket::OptionsSharedPtr getUpstreamSocketOptions() const PURE;
755 :
756 : /**
757 : * Set override host to be used by the upstream load balancing. If the target host exists in the
758 : * host list of the routed cluster, the host should be selected first.
759 : * @param host The override host address.
760 : */
761 : virtual void setUpstreamOverrideHost(Upstream::LoadBalancerContext::OverrideHost) PURE;
762 :
763 : /**
764 : * @return absl::optional<absl::string_view> optional override host for the upstream
765 : * load balancing.
766 : */
767 : virtual absl::optional<Upstream::LoadBalancerContext::OverrideHost>
768 : upstreamOverrideHost() const PURE;
769 : };
770 :
771 : /**
772 : * Common base class for both decoder and encoder filters. Functions here are related to the
773 : * lifecycle of a filter. Currently the life cycle is as follows:
774 : * - All filters receive onStreamComplete()
775 : * - All log handlers receive final log()
776 : * - All filters receive onDestroy()
777 : *
778 : * This means:
779 : * - onStreamComplete can be used to make state changes that are intended to appear in the final
780 : * access logs (like streamInfo().dynamicMetadata() or streamInfo().filterState()).
781 : * - onDestroy is used to cleanup all pending filter resources like pending http requests and
782 : * timers.
783 : */
784 : class StreamFilterBase {
785 : public:
786 1654 : virtual ~StreamFilterBase() = default;
787 :
788 : /**
789 : * This routine is called before the access log handlers' final log() is called. Filters can use
790 : * this callback to enrich the data passed in to the log handlers.
791 : */
792 609 : virtual void onStreamComplete() {}
793 :
794 : /**
795 : * This routine is called prior to a filter being destroyed. This may happen after normal stream
796 : * finish (both downstream and upstream) or due to reset. Every filter is responsible for making
797 : * sure that any async events are cleaned up in the context of this routine. This includes timers,
798 : * network calls, etc. The reason there is an onDestroy() method vs. doing this type of cleanup
799 : * in the destructor is due to the deferred deletion model that Envoy uses to avoid stack unwind
800 : * complications. Filters must not invoke either encoder or decoder filter callbacks after having
801 : * onDestroy() invoked. Filters that cross-register as access log handlers receive log() before
802 : * onDestroy().
803 : */
804 : virtual void onDestroy() PURE;
805 :
806 : /**
807 : * Called when a match result occurs that isn't handled by the filter manager.
808 : * @param action the resulting match action
809 : */
810 0 : virtual void onMatchCallback(const Matcher::Action&) {}
811 :
812 : struct LocalReplyData {
813 : // The error code which (barring reset) will be sent to the client.
814 : Http::Code code_;
815 : // The gRPC status set in local reply.
816 : absl::optional<Grpc::Status::GrpcStatus> grpc_status_;
817 : // The details of why a local reply is being sent.
818 : absl::string_view details_;
819 : // True if a reset will occur rather than the local reply (some prior filter
820 : // has returned ContinueAndResetStream)
821 : bool reset_imminent_;
822 : };
823 :
824 : /**
825 : * Called after sendLocalReply is called, and before any local reply is
826 : * serialized either to filters, or downstream.
827 : * This will be called on both encoder and decoder filters starting at the
828 : * terminal filter (generally the router filter) and working towards the first filter configured.
829 : *
830 : * Note that in some circumstances, onLocalReply may be called more than once
831 : * for a given stream, because it is possible that a filter call
832 : * sendLocalReply while processing the original local reply response.
833 : *
834 : * Filters implementing onLocalReply are responsible for never calling sendLocalReply
835 : * from onLocalReply, as that has the potential for looping.
836 : *
837 : * @param data data associated with the sendLocalReply call.
838 : * @param LocalErrorStatus the action to take after onLocalReply completes.
839 : */
840 264 : virtual LocalErrorStatus onLocalReply(const LocalReplyData&) {
841 264 : return LocalErrorStatus::Continue;
842 264 : }
843 : };
844 :
845 : /**
846 : * Stream decoder filter interface.
847 : */
848 : class StreamDecoderFilter : public StreamFilterBase {
849 : public:
850 : /**
851 : * Called with decoded headers, optionally indicating end of stream.
852 : * @param headers supplies the decoded headers map.
853 : * @param end_stream supplies whether this is a header only request/response.
854 : * @return FilterHeadersStatus determines how filter chain iteration proceeds.
855 : */
856 : virtual FilterHeadersStatus decodeHeaders(RequestHeaderMap& headers, bool end_stream) PURE;
857 :
858 : /**
859 : * Called with a decoded data frame.
860 : * @param data supplies the decoded data.
861 : * @param end_stream supplies whether this is the last data frame.
862 : * Further note that end_stream is only true if there are no trailers.
863 : * @return FilterDataStatus determines how filter chain iteration proceeds.
864 : */
865 : virtual FilterDataStatus decodeData(Buffer::Instance& data, bool end_stream) PURE;
866 :
867 : /**
868 : * Called with decoded trailers, implicitly ending the stream.
869 : * @param trailers supplies the decoded trailers.
870 : */
871 : virtual FilterTrailersStatus decodeTrailers(RequestTrailerMap& trailers) PURE;
872 :
873 : /**
874 : * Called with decoded metadata. Add new metadata to metadata_map directly. Do not call
875 : * StreamDecoderFilterCallbacks::addDecodedMetadata() to add new metadata.
876 : *
877 : * Note: decodeMetadata() currently cannot stop the filter iteration, and always returns Continue.
878 : * That means metadata will go through the complete filter chain at once, even if the other frame
879 : * types return StopIteration. If metadata should not pass through all filters at once, users
880 : * should consider using StopAllIterationAndBuffer or StopAllIterationAndWatermark in
881 : * decodeHeaders() to prevent metadata passing to the following filters.
882 : *
883 : * @param metadata_map supplies the decoded metadata.
884 : */
885 0 : virtual FilterMetadataStatus decodeMetadata(MetadataMap& /* metadata_map */) {
886 0 : return Http::FilterMetadataStatus::Continue;
887 0 : }
888 :
889 : /**
890 : * Called by the filter manager once to initialize the filter decoder callbacks that the
891 : * filter should use. Callbacks will not be invoked by the filter after onDestroy() is called.
892 : */
893 : virtual void setDecoderFilterCallbacks(StreamDecoderFilterCallbacks& callbacks) PURE;
894 :
895 : /**
896 : * Called at the end of the stream, when all data has been decoded.
897 : */
898 854 : virtual void decodeComplete() {}
899 : };
900 :
901 : using StreamDecoderFilterSharedPtr = std::shared_ptr<StreamDecoderFilter>;
902 :
903 : /**
904 : * Stream encoder filter callbacks add additional callbacks that allow a encoding filter to restart
905 : * encoding if they decide to hold data (e.g. for buffering or rate limiting).
906 : */
907 : class StreamEncoderFilterCallbacks : public virtual StreamFilterCallbacks {
908 : public:
909 : /**
910 : * Continue iterating through the filter chain with buffered headers and body data. This routine
911 : * can only be called if the filter has previously returned StopIteration from encodeHeaders() AND
912 : * one of StopIterationAndBuffer, StopIterationAndWatermark, or StopIterationNoBuffer
913 : * from each previous call to encodeData().
914 : *
915 : * The connection manager will dispatch headers and any buffered body data to the next filter in
916 : * the chain. Further note that if the response is not complete, this filter will still receive
917 : * encodeData() calls and must return an appropriate status code depending on what the filter
918 : * needs to do.
919 : */
920 : virtual void continueEncoding() PURE;
921 :
922 : /**
923 : * @return const Buffer::Instance* the currently buffered data as buffered by this filter or
924 : * previous ones in the filter chain. May be nullptr if nothing has been buffered yet.
925 : */
926 : virtual const Buffer::Instance* encodingBuffer() PURE;
927 :
928 : /**
929 : * Allows modifying the encoding buffer. May only be called before any data has been continued
930 : * past the calling filter.
931 : */
932 : virtual void modifyEncodingBuffer(std::function<void(Buffer::Instance&)> callback) PURE;
933 :
934 : /**
935 : * Add buffered body data. This method is used in advanced cases where returning
936 : * StopIterationAndBuffer from encodeData() is not sufficient.
937 : *
938 : * 1) If a headers only response needs to be turned into a response with a body, this method can
939 : * be called to add body in the encodeHeaders() callback. Subsequent filters will receive
940 : * encodeHeaders(..., false) followed by encodeData(..., true). This works both in the direct
941 : * iteration as well as the continuation case.
942 : *
943 : * 2) If a filter is going to look at all buffered data from within a data callback with end
944 : * stream set, this method can be called to immediately buffer the data. This avoids having
945 : * to deal with the existing buffered data and the data from the current callback.
946 : *
947 : * 3) If additional buffered body data needs to be added by a filter before continuation of data
948 : * to further filters (outside of callback context).
949 : *
950 : * 4) If additional data needs to be added in the encodeTrailers() callback, this method can be
951 : * called in the context of the callback. All further filters will receive encodeData(..., false)
952 : * followed by encodeTrailers(). However if the iteration is stopped, the added data will
953 : * buffered, so that the further filters will not receive encodeData() before encodeHeaders().
954 : *
955 : * It is an error to call this method in any other case.
956 : *
957 : * See also injectEncodedDataToFilterChain() for a different way of passing data to further
958 : * filters and also how the two methods are different.
959 : *
960 : * @param data Buffer::Instance supplies the data to be encoded.
961 : * @param streaming_filter boolean supplies if this filter streams data or buffers the full body.
962 : */
963 : virtual void addEncodedData(Buffer::Instance& data, bool streaming_filter) PURE;
964 :
965 : /**
966 : * Encode data directly to subsequent filters in the filter chain. This method is used in
967 : * advanced cases in which a filter needs full control over how subsequent filters view data,
968 : * and does not want to make use of HTTP connection manager buffering. Using this method allows
969 : * a filter to buffer data (or not) and then periodically inject data to subsequent filters,
970 : * indicating end_stream at an appropriate time. This can be used to implement rate limiting,
971 : * periodic data emission, etc.
972 : *
973 : * This method should only be called outside of callback context. I.e., do not call this method
974 : * from within a filter's encodeData() call.
975 : *
976 : * When using this callback, filters should generally only return
977 : * FilterDataStatus::StopIterationNoBuffer from their encodeData() call, since use of this method
978 : * indicates that a filter does not wish to participate in standard HTTP connection manager
979 : * buffering and continuation and will perform any necessary buffering and continuation on its
980 : * own.
981 : *
982 : * This callback is different from addEncodedData() in that the specified data and end_stream
983 : * status will be propagated directly to further filters in the filter chain. This is different
984 : * from addEncodedData() where data is added to the HTTP connection manager's buffered data with
985 : * the assumption that standard HTTP connection manager buffering and continuation are being used.
986 : */
987 : virtual void injectEncodedDataToFilterChain(Buffer::Instance& data, bool end_stream) PURE;
988 :
989 : /**
990 : * Adds encoded trailers. May only be called in encodeData when end_stream is set to true.
991 : * If called in any other context, an assertion will be triggered.
992 : *
993 : * When called in encodeData, the trailers map will be initialized to an empty map and returned by
994 : * reference. Calling this function more than once is invalid.
995 : *
996 : * @return a reference to the newly created trailers map.
997 : */
998 : virtual ResponseTrailerMap& addEncodedTrailers() PURE;
999 :
1000 : /**
1001 : * Attempts to create a locally generated response using the provided response_code and body_text
1002 : * parameters. If the request was a gRPC request the local reply will be encoded as a gRPC
1003 : * response with a 200 HTTP response code and grpc-status and grpc-message headers mapped from the
1004 : * provided parameters.
1005 : *
1006 : * If a response has already started (e.g. if the router calls sendLocalReply after encoding
1007 : * headers) this will either ship the reply directly to the downstream codec, or reset the stream.
1008 : *
1009 : * @param response_code supplies the HTTP response code.
1010 : * @param body_text supplies the optional body text which is sent using the text/plain content
1011 : * type, or encoded in the grpc-message header.
1012 : * @param modify_headers supplies an optional callback function that can modify the
1013 : * response headers.
1014 : * @param grpc_status the gRPC status code to override the httpToGrpcStatus mapping with.
1015 : * @param details a string detailing why this local reply was sent.
1016 : */
1017 : virtual void sendLocalReply(Code response_code, absl::string_view body_text,
1018 : std::function<void(ResponseHeaderMap& headers)> modify_headers,
1019 : const absl::optional<Grpc::Status::GrpcStatus> grpc_status,
1020 : absl::string_view details) PURE;
1021 : /**
1022 : * Adds new metadata to be encoded.
1023 : *
1024 : * @param metadata_map supplies the unique_ptr of the metadata to be encoded.
1025 : */
1026 : virtual void addEncodedMetadata(MetadataMapPtr&& metadata_map) PURE;
1027 :
1028 : /**
1029 : * Called when an encoder filter goes over its high watermark.
1030 : */
1031 : virtual void onEncoderFilterAboveWriteBufferHighWatermark() PURE;
1032 :
1033 : /**
1034 : * Called when a encoder filter goes from over its high watermark to under its low watermark.
1035 : */
1036 : virtual void onEncoderFilterBelowWriteBufferLowWatermark() PURE;
1037 :
1038 : /**
1039 : * This routine may be called to change the buffer limit for encoder filters.
1040 : *
1041 : * It is recommended (but not required) that filters calling this function should
1042 : * generally only perform increases to the buffer limit, to avoid potentially
1043 : * conflicting with the buffer requirements of other filters in the chain, i.e.
1044 : *
1045 : * if (desired_limit > encoderBufferLimit()) {setEncoderBufferLimit(desired_limit);}
1046 : *
1047 : * @param limit supplies the desired buffer limit.
1048 : */
1049 : virtual void setEncoderBufferLimit(uint32_t limit) PURE;
1050 :
1051 : /**
1052 : * This routine returns the current buffer limit for encoder filters. Filters should abide by
1053 : * this limit or change it via setEncoderBufferLimit.
1054 : * A buffer limit of 0 bytes indicates no limits are applied.
1055 : *
1056 : * @return the buffer limit the filter should apply.
1057 : */
1058 : virtual uint32_t encoderBufferLimit() PURE;
1059 : };
1060 :
1061 : /**
1062 : * Stream encoder filter interface.
1063 : */
1064 : class StreamEncoderFilter : public StreamFilterBase {
1065 : public:
1066 : /**
1067 : * Called with supported 1xx headers.
1068 : *
1069 : * This is not folded into encodeHeaders because most Envoy users and filters
1070 : * will not be proxying 1xxs and with it split out, can ignore the
1071 : * complexity of multiple encodeHeaders calls.
1072 : *
1073 : * This will only be invoked once per request.
1074 : *
1075 : * @param headers supplies the 1xx response headers to be encoded.
1076 : * @return Filter1xxHeadersStatus determines how filter chain iteration proceeds.
1077 : *
1078 : */
1079 : virtual Filter1xxHeadersStatus encode1xxHeaders(ResponseHeaderMap& headers) PURE;
1080 :
1081 : /**
1082 : * Called with headers to be encoded, optionally indicating end of stream.
1083 : *
1084 : * The only 1xx that may be provided to encodeHeaders() is a 101 upgrade, which will be the final
1085 : * encodeHeaders() for a response.
1086 : *
1087 : * @param headers supplies the headers to be encoded.
1088 : * @param end_stream supplies whether this is a header only request/response.
1089 : * @return FilterHeadersStatus determines how filter chain iteration proceeds.
1090 : */
1091 : virtual FilterHeadersStatus encodeHeaders(ResponseHeaderMap& headers, bool end_stream) PURE;
1092 :
1093 : /**
1094 : * Called with data to be encoded, optionally indicating end of stream.
1095 : * @param data supplies the data to be encoded.
1096 : * @param end_stream supplies whether this is the last data frame.
1097 : * Further note that end_stream is only true if there are no trailers.
1098 : * @return FilterDataStatus determines how filter chain iteration proceeds.
1099 : */
1100 : virtual FilterDataStatus encodeData(Buffer::Instance& data, bool end_stream) PURE;
1101 :
1102 : /**
1103 : * Called with trailers to be encoded, implicitly ending the stream.
1104 : * @param trailers supplies the trailers to be encoded.
1105 : */
1106 : virtual FilterTrailersStatus encodeTrailers(ResponseTrailerMap& trailers) PURE;
1107 :
1108 : /**
1109 : * Called with metadata to be encoded. New metadata should be added directly to metadata_map. DO
1110 : * NOT call StreamDecoderFilterCallbacks::encodeMetadata() interface to add new metadata.
1111 : *
1112 : * @param metadata_map supplies the metadata to be encoded.
1113 : * @return FilterMetadataStatus, which currently is always FilterMetadataStatus::Continue;
1114 : */
1115 : virtual FilterMetadataStatus encodeMetadata(MetadataMap& metadata_map) PURE;
1116 :
1117 : /**
1118 : * Called by the filter manager once to initialize the filter callbacks that the filter should
1119 : * use. Callbacks will not be invoked by the filter after onDestroy() is called.
1120 : */
1121 : virtual void setEncoderFilterCallbacks(StreamEncoderFilterCallbacks& callbacks) PURE;
1122 :
1123 : /**
1124 : * Called at the end of the stream, when all data has been encoded.
1125 : */
1126 164 : virtual void encodeComplete() {}
1127 : };
1128 :
1129 : using StreamEncoderFilterSharedPtr = std::shared_ptr<StreamEncoderFilter>;
1130 :
1131 : /**
1132 : * A filter that handles both encoding and decoding.
1133 : */
1134 : class StreamFilter : public virtual StreamDecoderFilter, public virtual StreamEncoderFilter {};
1135 :
1136 : using StreamFilterSharedPtr = std::shared_ptr<StreamFilter>;
1137 :
1138 : class HttpMatchingData {
1139 : public:
1140 375 : static absl::string_view name() { return "http"; }
1141 :
1142 2 : virtual ~HttpMatchingData() = default;
1143 :
1144 : virtual RequestHeaderMapOptConstRef requestHeaders() const PURE;
1145 : virtual RequestTrailerMapOptConstRef requestTrailers() const PURE;
1146 : virtual ResponseHeaderMapOptConstRef responseHeaders() const PURE;
1147 : virtual ResponseTrailerMapOptConstRef responseTrailers() const PURE;
1148 : virtual const StreamInfo::StreamInfo& streamInfo() const PURE;
1149 : virtual const Network::ConnectionInfoProvider& connectionInfoProvider() const PURE;
1150 :
1151 0 : const Network::Address::Instance& localAddress() const {
1152 0 : return *connectionInfoProvider().localAddress();
1153 0 : }
1154 :
1155 0 : const Network::Address::Instance& remoteAddress() const {
1156 0 : return *connectionInfoProvider().remoteAddress();
1157 0 : }
1158 :
1159 0 : Ssl::ConnectionInfoConstSharedPtr ssl() const { return connectionInfoProvider().sslConnection(); }
1160 : };
1161 :
1162 : /**
1163 : * These callbacks are provided by the connection manager to the factory so that the factory can
1164 : * build the filter chain in an application specific way.
1165 : */
1166 : class FilterChainFactoryCallbacks {
1167 : public:
1168 973 : virtual ~FilterChainFactoryCallbacks() = default;
1169 :
1170 : /**
1171 : * Add a decoder filter that is used when reading stream data.
1172 : * @param filter supplies the filter to add.
1173 : */
1174 : virtual void addStreamDecoderFilter(Http::StreamDecoderFilterSharedPtr filter) PURE;
1175 :
1176 : /**
1177 : * Add an encoder filter that is used when writing stream data.
1178 : * @param filter supplies the filter to add.
1179 : */
1180 : virtual void addStreamEncoderFilter(Http::StreamEncoderFilterSharedPtr filter) PURE;
1181 :
1182 : /**
1183 : * Add a decoder/encoder filter that is used both when reading and writing stream data.
1184 : * @param filter supplies the filter to add.
1185 : */
1186 : virtual void addStreamFilter(Http::StreamFilterSharedPtr filter) PURE;
1187 :
1188 : /**
1189 : * Add an access log handler that is called when the stream is destroyed.
1190 : * @param handler supplies the handler to add.
1191 : */
1192 : virtual void addAccessLogHandler(AccessLog::InstanceSharedPtr handler) PURE;
1193 :
1194 : /**
1195 : * Allows filters to access the thread local dispatcher.
1196 : * @param return the worker thread's dispatcher.
1197 : */
1198 : virtual Event::Dispatcher& dispatcher() PURE;
1199 : };
1200 : } // namespace Http
1201 : } // namespace Envoy
|
