/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    h2: "h2",
    a: "a",
    p: "p",
    pre: "pre",
    code: "code",
    span: "span",
    ul: "ul",
    li: "li"
  }, props.components), {Alert} = _components;
  if (!Alert) _missingMdxReference("Alert", true);
  return _jsxs(_Fragment, {
    children: [_jsxs(_components.h2, {
      id: "introduction",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#introduction"
      }), "Introduction"]
    }), "\n", _jsxs(_components.p, {
      children: [_jsx(_components.a, {
        href: "https://github.com/eclipse-vertx/vertx-http-proxy",
        children: "vertx-​http-proxy"
      }), " is a com­po­nent in the Vert.x ecosys­tem often used\nas an HTTP re­verse proxy. Com­ing from Google Sum­mer of Code 2024, some new fea­tures are im­ple­mented under this\nproject to make its usage eas­ier and elim­i­nate boil­er­plate code re­quired for com­mon sce­nar­ios. In this blog post, I\nin­tro­duce some fea­tures that are about to be in­cluded in the of­fi­cial re­lease and how to use them, fol­lowed by re­flec­tions\non the GSoC ex­pe­ri­ence."]
    }), "\n", _jsx(Alert, {
      warning: true,
      children: _jsx(_components.p, {
        children: "The up­dates men­tioned in this post are not yet avail­able from the maven repos­i­tory. The ac­tual re­sults are sub­ject\nto the final pro­vided API."
      })
    }), "\n", _jsxs(_components.h2, {
      id: "interceptors",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#interceptors"
      }), "Interceptors"]
    }), "\n", _jsx(_components.p, {
      children: "Dur­ing HTTP ex­changes, de­vel­op­ers can mod­ify in­com­ing re­quests and re­sponses with in­ter­cep­tors.\nThis up­date pro­vides a quick way to cre­ate dif­fer­ent types of in­ter­cep­tors. For ex­am­ple,\nIn the pre­vi­ous ver­sion, if you wanted to re­move cer­tain fields from the header, you had to cre­ate\nthe in­ter­cep­tor like this:"
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: ["proxy.addInterceptor(", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "new"
        }), " ", _jsx(_components.span, {
          className: "hljs-title class_",
          children: "ProxyInterceptor"
        }), "() {\n    ", _jsx(_components.span, {
          className: "hljs-meta",
          children: "@Override"
        }), "\n    ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "public"
        }), " Future<ProxyResponse> ", _jsx(_components.span, {
          className: "hljs-title function_",
          children: "handleProxyRequest"
        }), _jsx(_components.span, {
          className: "hljs-params",
          children: "(ProxyContext context)"
        }), " {\n    context.request().headers().remove(", _jsx(_components.span, {
          className: "hljs-string",
          children: "\"header-to-remove\""
        }), ");\n    ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "return"
        }), " context.sendRequest();\n    }\n});\n"]
      })
    }), "\n", _jsx(_components.p, {
      children: "Now it’s pos­si­ble to cre­ate an in­ter­cep­tor to fil­ter head­ers with a sin­gle method:"
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: ["proxy.addInterceptor(\n    HeadersInterceptor.filterRequestHeaders(Set.of(", _jsx(_components.span, {
          className: "hljs-string",
          children: "\"header-to-remove\""
        }), ")));\n"]
      })
    }), "\n", _jsxs(_components.p, {
      children: ["We can now also use the ", _jsx(_components.code, {
        children: "BodyInterceptor"
      }), " to con­ve­niently mod­ify the body of re­quests or re­sponses.\nThis in­ter­cep­tor sup­ports var­i­ous types of data by de­fault, mean­ing that you can treat the body\ndi­rectly as ei­ther bytes, strings, or json types for trans­for­ma­tion by using ", _jsx(_components.code, {
        children: "BodyTransformer"
      }), ".\nFor ex­am­ple, to cre­ate an in­ter­cep­tor that re­moves the ", _jsx(_components.code, {
        children: "id"
      }), " field from each item in the\nre­sponse json array:"]
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: ["BodyInterceptor.modifyResponseBody(BodyTransformer.transformJsonArray(arr -> {\n    arr.forEach(json -> ((JsonObject) json).remove(", _jsx(_components.span, {
          className: "hljs-string",
          children: "\"id\""
        }), "));\n    ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "return"
        }), " arr;\n}))\n"]
      })
    }), "\n", _jsx(_components.p, {
      children: "Here’s a list of all the in­ter­cep­tors im­ple­mented:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "HeadersInterceptor"
        }), ": Used to mod­ify the head­ers of HTTP re­quests and re­sponses;"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "PathInterceptor"
        }), ": used to mod­ify the URI of the re­quest;"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "QueryInterceptor"
        }), ": used to mod­ify the query pa­ra­me­ter of the re­quest;"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "BodyInterceptor"
        }), ": used to mod­ify the body of the re­quest and re­sponse."]
      }), "\n"]
    }), "\n", _jsxs(_components.p, {
      children: ["For mod­i­fi­ca­tion de­tails, see the PR ", _jsx(_components.a, {
        href: "https://github.com/eclipse-vertx/vertx-http-proxy/pull/78",
        children: "here"
      }), "."]
    }), "\n", _jsxs(_components.p, {
      children: ["Ad­di­tion­ally, it is now pos­si­ble to apply in­ter­cep­tors to Web­Socket hand­shake pack­ets. This means that you can now\nmod­ify the Web­Socket re­quest URL using an in­ter­cep­tor. Con­sid­er­ing that in most cases you might not want\nto apply all in­ter­cep­tor trans­for­ma­tions dur­ing the Web­Socket hand­shake (which could lead to con­nec­tion fail­ures),\nin­ter­cep­tors are dis­abled for Web­Socket by de­fault. You can en­able this be­hav­ior by over­rid­ing the ", _jsx(_components.code, {
        children: "allowApplyToWebSocket"
      }), "\nmethod. For in­ter­cep­tors that have al­ready been cre­ated, you can also achieve this by wrap­ping them with\n", _jsx(_components.code, {
        children: "WebSocketInterceptor"
      }), ":"]
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: [_jsx(_components.span, {
          className: "hljs-type",
          children: "ProxyInterceptor"
        }), " ", _jsx(_components.span, {
          className: "hljs-variable",
          children: "addPrefix"
        }), " ", _jsx(_components.span, {
          className: "hljs-operator",
          children: "="
        }), " PathInterceptor.addPrefix(", _jsx(_components.span, {
          className: "hljs-string",
          children: "\"/api\""
        }), ");\naddPrefix = WebSocketInterceptor.allow(addPrefix); ", _jsx(_components.span, {
          className: "hljs-comment",
          children: "// now `addPrefix` can be applied to WebSocket\t"
        }), "\n"]
      })
    }), "\n", _jsxs(_components.p, {
      children: ["For the Web­Socket in­ter­cep­tor, see the changes in this ", _jsx(_components.a, {
        href: "https://github.com/eclipse-vertx/vertx-http-proxy/pull/95",
        children: "PR"
      }), "."]
    }), "\n", _jsxs(_components.h2, {
      id: "cache-support",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#cache-support"
      }), "Cache Support"]
    }), "\n", _jsxs(_components.p, {
      children: ["The proxy sup­ports caching re­sponses. In pre­vi­ous ver­sions, caching was only al­lowed for re­sponses with the ", _jsx(_components.code, {
        children: "Cache-Control"
      }), "\nheader marked as ", _jsx(_components.code, {
        children: "public"
      }), ". This up­date im­proves the caching mech­a­nism and meets most of the re­quire­ments of\n", _jsx(_components.a, {
        href: "https://www.rfc-editor.org/rfc/rfc9111.html",
        children: "RFC9111"
      }), ". The spe­cific changes are as fol­lows:"]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: ["Im­ple­mented all cache re­quest and re­sponse di­rec­tives from RFC9111 (ex­cept ", _jsx(_components.code, {
          children: "no-transform"
        }), ");"]
      }), "\n", _jsx(_components.li, {
        children: "By de­fault, all re­sponses are now al­lowed to be cached un­less ex­plic­itly pro­hib­ited in the Cache-​Control header;"
      }), "\n", _jsx(_components.li, {
        children: "More stan­dard reval­i­da­tion mech­a­nism: ex­pired caches will not be im­me­di­ately deleted but will first be val­i­dated to de­ter­mine if they can still be used;"
      }), "\n", _jsxs(_components.li, {
        children: ["Now reval­i­da­tion sup­ports both ", _jsx(_components.code, {
          children: "ETag"
        }), " and ", _jsx(_components.code, {
          children: "Last-Modified"
        }), " val­ida­tors;"]
      }), "\n", _jsx(_components.li, {
        children: "Fixed the issue where call­ing un­safe re­quest meth­ods would not in­val­i­date the cache;"
      }), "\n", _jsxs(_components.li, {
        children: ["Fixed the issue with wrong caching re­sponses when in­clud­ing the ", _jsx(_components.code, {
          children: "Vary"
        }), " header;"]
      }), "\n", _jsx(_components.li, {
        children: "Im­ple­mented de­fault heuris­tic fresh­ness."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "A Cache SPI is also cur­rently pro­vided to sup­port cus­tom dif­fer­ent Cache im­ple­men­ta­tions (e.g. on heap or Redis)."
    }), "\n", _jsxs(_components.p, {
      children: ["See code changes in for HTTP cache sup­port in this ", _jsx(_components.a, {
        href: "https://github.com/eclipse-vertx/vertx-http-proxy/pull/93",
        children: "PR"
      }), " and\nCache SPI up­date in this ", _jsx(_components.a, {
        href: "https://github.com/eclipse-vertx/vertx-http-proxy/pull/92",
        children: "PR"
      }), "."]
    }), "\n", _jsxs(_components.h2, {
      id: "contextual-data",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#contextual-data"
      }), "Contextual Data"]
    }), "\n", _jsxs(_components.p, {
      children: [_jsx(_components.code, {
        children: "ProxyContext"
      }), " is used as a con­text for shar­ing state be­tween dif­fer­ent proxy com­po­nents. In the lat­est ver­sion, it\ncan be more gen­er­ally shared be­tween in­ter­cep­tors and the ", _jsx(_components.code, {
        children: "originSelector"
      }), ". Since in­ter­cep­tors now sup­port Web­Socket,\nthe con­text can also be used dur­ing the Web­Socket hand­shake."]
    }), "\n", _jsx(_components.p, {
      children: "The new ver­sion of the con­text also al­lows an ad­di­tional map to be passed in as a con­tex­tual data holder when han­dling\nre­quests. This method en­ables the in­jec­tion of cus­tom con­text con­tent at run­time. For ex­am­ple, to reg­is­ter a proxy\nas a han­dler for an HTTP server with cus­tom con­text, you can using the fol­low­ing code:"
    }), "\n", _jsx(_components.pre, {
      children: _jsxs(_components.code, {
        className: "hljs language-java",
        children: ["server.requestHandler(request -> {\n    Map<String, Object> customContext = ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "new"
        }), " ", _jsx(_components.span, {
          className: "hljs-title class_",
          children: "HashMap"
        }), "<>(); ", _jsx(_components.span, {
          className: "hljs-comment",
          children: "// inject any additional data here"
        }), "\n    proxy.handle(request, customContext);\n});\n"]
      })
    }), "\n", _jsxs(_components.p, {
      children: ["It is also planned for ", _jsx(_components.a, {
        href: "https://github.com/vert-x3/vertx-web",
        children: "vertx-​web-proxy"
      }), " to set the ", _jsx(_components.code, {
        children: "RoutingContext"
      }), " bound to\nthe re­quest as cus­tom proxy con­text."]
    }), "\n", _jsxs(_components.p, {
      children: ["See this ", _jsx(_components.a, {
        href: "https://github.com/eclipse-vertx/vertx-http-proxy/pull/96",
        children: "PR"
      }), " for the con­tex­tual data changes."]
    }), "\n", _jsxs(_components.h2, {
      id: "gsoc-experience--learnings",
      children: [_jsx(_components.a, {
        "aria-hidden": true,
        tabIndex: "-1",
        className: "heading-anchor",
        href: "#gsoc-experience--learnings"
      }), "GSoC Experience & Learnings"]
    }), "\n", _jsx(_components.p, {
      children: "The most in­ter­est­ing (and hard) of this project was the de­sign process. Most of my work in­volved adding new fea­tures\nto an ex­ist­ing code­base, which re­quired a lot of API de­sign. The chal­lenge was en­sur­ing that the API was easy to\nun­der­stand and use while avoid­ing any dis­rup­tive changes to the orig­i­nal code, which sig­nif­i­cantly lim­ited the final\nfea­si­ble de­sign op­tions."
    }), "\n", _jsx(_components.p, {
      children: "For ex­am­ple, there was an issue re­gard­ing mak­ing the In­ter­cep­tor sup­port Web­Socket. In the orig­i­nal code, Web­Socket\npack­ets and reg­u­lar HTTP pack­ets were han­dled sep­a­rately, so only the branch pro­cess­ing HTTP pack­ets ap­plied the\nin­ter­cep­tors. This was rea­son­able be­cause the han­dling meth­ods for the two were en­tirely dif­fer­ent. How­ever, the\nuser’s re­quest to im­ple­ment this fea­ture was also rea­son­able, as the need to mod­ify the Web­Socket path ex­ists.\nBal­anc­ing these two re­quire­ments took a lot of time dur­ing the “find­ing a fea­si­ble so­lu­tion” phase."
    }), "\n", _jsx(_components.p, {
      children: "Even after the fea­ture was im­ple­mented, I had to con­sider user ex­pe­ri­ence. If the in­ter­cep­tor were to han­dle all\ntypes of re­quests by de­fault, users would need to add a con­di­tion to all reg­u­lar in­ter­cep­tors to skip Web­Socket\ntraf­fic, as most re­quest trans­for­ma­tions shouldn’t apply to them. There­fore, I have to think about a so­lu­tion where\nthe in­ter­cep­tor doesn’t af­fect Web­Socket by de­fault, which also took con­sid­er­able time."
    }), "\n", _jsx(_components.p, {
      children: "In fact, the ef­fec­tive time spent writ­ing code was only one day or even half a day, while the de­sign time was one\nto two times that. So, if I had to sum­ma­rize the most im­por­tant lessons:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "De­sign process is more im­por­tant than cod­ing; it’s best to ex­plic­itly al­lo­cate time for it dur­ing plan­ning."
      }), "\n", _jsx(_components.li, {
        children: "It’s bet­ter to seek feed­back after com­plet­ing the de­sign im­me­di­ately rather than jump­ing straight into cod­ing, as this can eas­ily lead to un­ex­pected out­comes."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "And fi­nally, I would like to thank my men­tor, Thomas Segis­mont, for his help­ful ad­vice and sup­port through­out the project."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};
function _missingMdxReference(id, component) {
  throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it.");
}


Blog

Upcoming Vert.x Http Proxy updates

Next post

Eclipse Vert.x 4.5.10 released!

Previous post

Eclipse Vert.x 4.5.9 released!

Blog

Upcoming Vert.x Http Proxy updates

Next post

Eclipse Vert.x 4.5.10 released!

Previous post

Eclipse Vert.x 4.5.9 released!

Related posts

Things to keep in mind concerning CSRF attacks

Some Rest with Vert.x

An Introduction to the Vert.x Context Object