{"id":109028,"date":"2023-11-17T07:00:00","date_gmt":"2023-11-17T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=109028"},"modified":"2023-11-19T10:50:27","modified_gmt":"2023-11-19T18:50:27","slug":"20231117-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20231117-00\/?p=109028","title":{"rendered":"The theory behind the IHttpFilter interface"},"content":{"rendered":"

The Windows Runtime has an interface called IHttpFilter<\/code> that lets you customize how HTTP requests are processed. The system has a default implementation called Http\u00adBase\u00adProtocol\u00adFilter<\/code>, and if it has the features you need, then you’re all set:<\/p>\n

auto filter = HttpBaseProtocolFilter();\r\nfilter.AllowAutoRedirect(false); \/\/ disable auto-redirect\r\nauto client = HttpClient(filter);\r\n\u27e6 Use the client \u27e7\r\n<\/pre>\n
But maybe you want to do something beyond that. For example, maybe you want a filter that injects an extra header into each request. You can implement these extra features by providing your own implementation of IHttpFilter<\/code>, using the default implementation to do the heavy lifting.<\/p>\n
\/\/ IDL\r\nruntimeclass ExtraHeadersHttpFilter : Windows.Web.Http.Filters.IHttpFilter\r\n{\r\n    ExtraHeadersHttpFilter();\r\n    void AddHeader(string name, string value);\r\n}\r\n\r\n\/\/ Implementation\r\n\r\nstruct ExtraHeadersHttpFilter : ExtraHeadersHttpFilterT<ExtraHeadersHttpFilter>\r\n{\r\n    using namespace Http = winrt::Windows::Web::Http;\r\nprivate:\r\n    \/\/ Data members\r\n    std::mutex m_mutex;\r\n    std::unordered_map<winrt::hstring, winrt::hstring> m_extraHeaders;\r\n    Http::Filters::HttpBaseProtocolFilter m_base = Http:Filters::HttpBaseProtocolFilter();\r\n\r\npublic:\r\n    ExtraHeadersHttpFilter() = default;\r\n\r\n    \/\/ Bonus methods for public consumption\r\n    void AddHeader(winrt::hstring const& name,\r\n                   winrt::hstring const& value)\r\n    {\r\n        auto lock = std::lock_guard(m_mutex);\r\n        m_extraHeaders.insert_or_assign(name, value);\r\n    }\r\n\r\n    \/\/ IHttpFilter methods\r\n    winrt::Windows::Foundation::IAsyncOperationWithProgress<Http::HttpResponseMessage,\r\n        Http::HttpProgress> SendRequestAsync(Http::HttpRequestMessage request)\r\n    {\r\n        \/\/ Add our bonus headers to the request\r\n        {\r\n            auto lock = std::lock_guard(m_mutex);\r\n            auto headers = request.Headers();\r\n            for (auto [name, value] : m_extraHeaders) {\r\n                headers.Insert(name, value);\r\n            }\r\n        }\r\n\r\n        \/\/ And then use default handling for the rest.\r\n        return m_base.SendRequestAsync(request);\r\n    }\r\n};\r\n\r\n\/\/ Consumer\r\nauto filter = ExtraHeadersHttpFilter();\r\nfilter.AddHeader(L\"X-Contoso\", L\"Awesome\");\r\nauto client = HttpClient(filter);\r\n\u27e6 Use the client \u27e7\r\n<\/pre>\n
One thing that people like to do is stack filters on top of each other. Maybe you want to use the Extra\u00adHeaders\u00adHttp\u00adFilter<\/code> in conjunction with a Custom\u00adRetry\u00adHttp\u00adFilter<\/code>. Right now, the Extra\u00adHeaders\u00adHttp\u00adFilter<\/code> hands all of its requests to the default Http\u00adBase\u00adProtocol\u00adFilter<\/code>, so there’s no way to combine it with a Custom\u00adRetry\u00adHttp\u00adFilter<\/code>.<\/p>\n
The way to fix this is to give the Extra\u00adHeaders\u00adHttp\u00adFilter<\/code> a constructor that takes another filter. Requests then pass through that custom filter instead of going to the default filter.<\/p>\n
\/\/ IDL\r\nruntimeclass ExtraHeadersHttpFilter : Windows.Web.Http.Filters.IHttpFilter\r\n{\r\n    ExtraHeadersHttpFilter();\r\n    ExtraHeadersHttpFilter(Windows.Web.Http.Filters.IHttpFilter baseFilter);<\/span>\r\n    void AddHeader(string name, string value);\r\n}\r\n\r\n\/\/ Implementation\r\n\r\nstruct ExtraHeadersHttpFilter : ExtraHeadersHttpFilterT<ExtraHeadersHttpFilter>\r\n{\r\n    using namespace Http = winrt::Windows::Web::Http;\r\nprivate:\r\n    \/\/ Data members\r\n    std::mutex m_mutex;\r\n    std::unordered_map<winrt::hstring, winrt::hstring> m_extraHeaders;\r\n    Http:Filters::IHttpFilter<\/span> m_base = Http:Filters::HttpBaseProtocolFilter();\r\n\r\npublic:\r\n    ExtraHeadersHttpFilter() = default;\r\n\r\n    ExtraHeadersHttpFilter(Http::Filters::IHttpFilter const& baseFilter) :<\/span>\r\n        m_base(baseFilter) {}                                             <\/span>\r\n\r\n    \/\/ Bonus methods for public consumption\r\n    void AddHeader(winrt::hstring const& name,\r\n                   winrt::hstring const& value)\r\n    {\r\n        auto lock = std::lock_guard(m_mutex);\r\n        m_extraHeaders.insert_or_assign(name, value);\r\n    }\r\n\r\n    \/\/ IHttpFilter methods\r\n    winrt::Windows::Foundation::IAsyncOperationWithProgress<Http::HttpResponseMessage,\r\n        Http::HttpProgress> SendRequestAsync(Http::HttpRequestMessage request)\r\n    {\r\n        \/\/ Add our bonus headers to the request\r\n        {\r\n            auto lock = std::lock_guard(m_mutex);\r\n            auto headers = request.Headers();\r\n            for (auto [name, value] : m_extraHeaders) {\r\n                headers.Insert(name, value);\r\n            }\r\n        }\r\n\r\n        \/\/ And then pass the request to the base filter.<\/span>\r\n        return m_base.SendRequestAsync(request);\r\n    }\r\n};\r\n\r\n\/\/ Consumer\r\nauto retryFilter = CustomRetryHttpFilter(3);\r\nauto headerFilter = ExtraHeadersHttpFilter(retryFilter);\r\nheaderFilter.AddHeader(L\"X-Contoso\", L\"Awesome\");\r\nauto client = HttpClient(headerFilter);\r\n\u27e6 Use the client \u27e7\r\n<\/pre>\n
The idea behind HTTP filters is that each request passes through the filters before hitting the wire, and then the response passes through the filters on the way back.<\/p>\n\n\n\n\n\n\n
App<\/td>\n <\/td>\nFilter1<\/td>\n <\/td>\nFilter2<\/td>\n <\/td>\n <\/td>\n <\/td>\nFilterN<\/td>\n <\/td>\nNetwork<\/td>\n<\/tr>\n
Request<\/td>\n\u2192<\/td>\n\u2022<\/td>\n\u2192<\/td>\n\u2022<\/td>\n\u2192<\/td>\n\u2026<\/td>\n\u2192<\/td>\n\u2022<\/td>\n\u2192<\/td>\n\u21b4<\/td>\n<\/tr>\n
\u00a0<\/td>\n <\/td>\n\u00a0<\/td>\n <\/td>\n\u2191<\/td>\n <\/td>\n\u2026<\/td>\n <\/td>\n\u00a0<\/td>\n <\/td>\n\u2022<\/td>\n<\/tr>\n
\u2022<\/td>\n\u2190<\/td>\n\u2022<\/td>\n\u2190<\/td>\n\u2022<\/td>\n\u2190<\/td>\n\u2026<\/td>\n\u2190<\/td>\n\u2022<\/td>\n\u2190<\/td>\nResponse<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
In the above diagram, Filter2 is a Retry filter, so when it gets a response, it might decide to generate a new request and submit that one down the pipeline.<\/p>\n
Basically, each filter can treat the remainder of the pipeline as a black box which conceptually submits the request and produces a result. Your filter doesn’t even have to submit the request down the pipeline; maybe it sees something wrong with the request and chooses to generate an error response without actually hitting the wire. Or it might submit the request to two downstream pipelines for some reason. Or you may have a custom filter for testing purposes that replays prerecorded Web responses without every submitting them to the network at all. Each filter can decide whatever it likes.<\/p>\n
Bonus chatter<\/b>: For expository purposes, I didn’t show how to modify the result. You can find an example of that in the HttpClient sample’s  PluginFilter<\/a> filter.<\/p>\n","protected":false},"excerpt":{"rendered":"
Layering features on top of each other.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-109028","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Layering features on top of each other.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/109028","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=109028"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/109028\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=109028"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=109028"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=109028"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}