{"id":15022614,"url":"https://github.com/puppetlabs/trapperkeeper-webserver-jetty9","last_synced_at":"2025-08-17T18:36:57.835Z","repository":{"id":12967683,"uuid":"15646171","full_name":"puppetlabs/trapperkeeper-webserver-jetty9","owner":"puppetlabs","description":"Trapperkeeper webservice service (jetty9 implementation).","archived":false,"fork":false,"pushed_at":"2025-02-04T02:10:47.000Z","size":1593,"stargazers_count":17,"open_issues_count":4,"forks_count":45,"subscribers_count":163,"default_branch":"main","last_synced_at":"2025-04-12T17:48:01.334Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tickets.puppetlabs.com/browse/TK","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-01-05T05:40:45.000Z","updated_at":"2025-01-13T14:37:44.000Z","dependencies_parsed_at":"2024-05-09T19:40:15.772Z","dependency_job_id":"e32268cd-9134-474d-9fa5-4a682a90cf7a","html_url":"https://github.com/puppetlabs/trapperkeeper-webserver-jetty9","commit_stats":{"total_commits":755,"total_committers":50,"mean_commits":15.1,"dds":0.8013245033112583,"last_synced_commit":"818094268f7787dcb8607b602ea7a9b7533f860c"},"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Ftrapperkeeper-webserver-jetty9","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Ftrapperkeeper-webserver-jetty9/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Ftrapperkeeper-webserver-jetty9/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Ftrapperkeeper-webserver-jetty9/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/trapperkeeper-webserver-jetty9/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592368,"owners_count":22097011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:58:12.303Z","updated_at":"2025-05-16T19:03:19.202Z","avatar_url":"https://github.com/puppetlabs.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/puppetlabs/trapperkeeper-webserver-jetty9.png?branch=master)](https://travis-ci.org/puppetlabs/trapperkeeper-webserver-jetty9)\n\n## Trapperkeeper Webserver Service\n\nThis project provides a webserver service for use with the\n[trapperkeeper service framework](https://github.com/puppetlabs/trapperkeeper)\nTo use this service in your trapperkeeper application, simply add this\nproject as a dependency in your leiningen project file:\n\n[![Clojars Project](http://clojars.org/puppetlabs/trapperkeeper-webserver-jetty9/latest-version.svg)](http://clojars.org/puppetlabs/trapperkeeper-webserver-jetty9)\n\nThen add the webserver service to your [`bootstrap.cfg`](https://github.com/puppetlabs/trapperkeeper#bootstrapping)\nfile, via:\n\n    puppetlabs.trapperkeeper.services.webserver.jetty9-service/jetty9-service\n\nNote that this implementation of the\n`:WebserverService` interface is based on Jetty 9, which contains performance\nimprovements over previous versions of Jetty that may be significant depending on\nyour application.  This service requires JRE 1.7 or greater;\nhowever, the interface is intended to be agnostic to the underlying web server\nimplementation.  We also provide a\n[Jetty 7 version of the service](https://github.com/puppetlabs/trapperkeeper-webserver-jetty7),\nwhich can be used interchangeably with this one and will support older JDKs.\nYou should only need to change your lein dependencies and your `bootstrap.cfg`\nfile--no code changes.\n\nThe web server is configured via the\n[trapperkeeper configuration service](https://github.com/puppetlabs/trapperkeeper#configuration-service);\nso, you can control various properties of the server (ports, SSL, etc.) by adding a `webserver`\nsection to one of your Trapperkeeper configuration files, and setting various properties\ntherein.  For more info, see [Configuring the Webserver](doc/jetty-config.md). It is possible to configure\nboth a single webserver or multiple webservers.\n\nThe `webserver-service` currently supports web applications built using\nClojure's [Ring](https://github.com/ring-clojure/ring) library and Java's Servlet\nAPI.  There is also an experimental webserver service that supports loading\nruby Rack applications via JRuby; for more info, see the\n[trapperkeeper-ruby](https://github.com/puppetlabs/trapperkeeper-ruby) project.\n\n### Example code\n\nFour examples are included with this project:\n\n* A Ring example ([source code](./examples/ring_app))\n* A Java servlet example ([source code](./examples/servlet_app))\n* A WAR example ([source code](./examples/war_app))\n* A multiserver configuration example ([source code](./examples/multiserver_app))\n\n### Service Protocol\n\nThis is the protocol for the current implementation of the `:WebserverService`:\n\n```clj\n(defprotocol WebserverService\n  (add-context-handler [this base-path context-path] [this base-path context-path options])\n  (add-ring-handler [this handler path] [this handler path options])\n  (add-websocket-handler [this handlers path] [this handler path options])\n  (add-servlet-handler [this servlet path] [this servlet path options])\n  (add-war-handler [this war path] [this war path options])\n  (add-proxy-route [this target path] [this target path options])\n  (override-webserver-settings! [this overrides] [this server-id overrides])\n  (get-registered-endpoints [this] [this server-id])\n  (log-registered-endpoints [this] [this server-id])\n  (join [this] [this server-id])\n```\n\nHere is a bit more info about each of these functions:\n\n#### `add-ring-handler`\n\n`add-ring-handler` takes two arguments: `[handler path]`.  The `handler` argument\nis just a normal Ring application (the same as what you would pass to `run-jetty`\nif you were using the `ring-jetty-adapter`).  The `path` is a URL prefix / context\nstring that will be prepended to all your handler's URLs; this is key to allowing\nthe registration of multiple handlers in the same web server without the possibility\nof URL collisions.  So, for example, if your ring handler has routes `/foo` and\n`/bar`, and you call:\n\n```clj\n(add-ring-handler my-app \"/my-app\")\n```\n\nThen your routes will be served at `/my-app/foo` and `my-app/bar`.\n\nYou may specify `\"\"` as the value for `path` if you are only registering a single\nhandler and do not need to prefix the URL.\n\nThere is also a three argument version of this function which takes these arguments:\n`[handler path options]`. `options` is a map containing optional keys.\n\n* `:server-id`\n\n  This option specifies which server you want to add the ring-handler\n  to. If `:server-id` is specified, the ring handler will be added to\n  the server with id `:server-id`. If no `:server-id` is specified, or\n  the two argument version is called, the ring handler will be added\n  to the default server. Calling the two-argument version or leaving\n  out `:server-id` will not work in a multiserver set-up if no default\n  server is specified.\n\n* `:redirect-if-no-trailing-slash`\n\n  When set to `true`, all requests made to the endpoint at which the\n  ring-handler was registered will, if no trailing slash is present,\n  return a 302 redirect response to the same URL but with a trailing\n  slash added. If the option is set to `false`, no redirect will\n  occur, and the request will be routed through to the registered\n  handler. This option defaults to `false`.\n\n* `:normalize-request-uri`\n\n  When set to `true`, the URI made available to the ring handler\n  request map via the `:uri` key will have been \"normalized\".  See the\n  [Request URI Normalization] (#request-uri-normalization) section for\n  more information on the normalization process.  When set to `false`\n  (the default value), the raw path component from the HTTP request\n  URI will be the value for the `:uri` key.\n\n* `:include-response`\n\n  When set to `true`, the request will include the pending jetty\n  [`Response`](https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/Response.html)\n  instance as `:puppetlabs.trapperkeeper.services.webserver.jetty9/response`.\n\nHere's an example of how to use the `:WebserverService`:\n\n```clj\n(defservice MyWebService\n   [[:WebserverService add-ring-handler]]\n   ;; initialization\n   (init [this context]\n      (add-ring-handler my-app \"/my-app\")\n      context))\n```\n\nThis would add your ring handler to the default server at endpoint \"/my-app\".\nAlternatively, if you did this:\n\n```clj\n(defservice MyWebService\n   [[:WebserverService add-ring-handler]]\n   ;; initialization\n   (init [this context]\n      (add-ring-handler my-app \"/my-app\" {:server-id :foo})\n      context))\n```\nit would add your ring handler to the server with id `:foo` at endpoint \"/my-app\",\nrather than the default server.\n\n*NOTE FOR COMPOJURE APPS*: If you are using compojure, it's important to note\nthat compojure requires use of the [`context` macro](https://github.com/weavejester/compojure/wiki/Nesting-routes)\nin order to support nested routes.  So, if you're not already using `context`,\nyou will need to do something like this:\n\n```clj\n(ns foo\n   (:require [compojure.core :as c]\n   ;;...\n   ))\n\n(defservice MyWebService\n   [[:WebserverService add-ring-handler]]\n   ;; initialization\n   (init [this svc-context]\n        (let [context-path \"/my-app\"\n              context-app  (c/context context-path [] my-compojure-app)]\n            (add-ring-handler context-app context-path))\n        svc-context))\n```\n\n##### Request URI Normalization\n\nThe `:normalize-request-uri` setting, which can be provided in the `options`\nargument for an add handler call, controls whether or not the\n[path component](https://tools.ietf.org/html/rfc3986#section-3.3) from the HTTP\nrequest URI is normalized.  The value for the setting is expected to be a\nboolean.\n\nWhen set to `false` (the default value), the \"raw\" path component will be\nused by the webserver when evaluating a request to the handler.\n\nWhen set to `true`, the path component that the webserver evaluates for a\nrequest to the handler will have been \"normalized\". For a Ring request handler,\nthe \"normalized\" value (instead of the \"raw\" value) will be associated with the\n`:uri` key in the Ring request map.  For a Servlet request handler, the\n\"normalized\" value (instead of the \"raw\" value) will be returned from a call\nmade to the `getRequestURI` method on the `HttpServletRequest` object.\n\nThe following steps, in order, are performed against the raw path component\nwhen the `:normalize-request-uri` setting is true:\n\n1. URL (percent) decode the path, assuming any percent-encodings represent UTF-8\n   characters.\n\n  For example:\n\n  ```\n  /foo//bar/%2E%2E/ba%7A =\u003e /foo//bar/../baz\n  ```\n  \n  If a non-percent encoded semicolon character, U+003B, is found in the path\n  during the percent decoding step, that character and all following characters\n  will be removed from the resulting path, unless there is another forward\n  slash, in which case the characters from the semicolon to the next forward\n  slash (including the semicolon) will be removed.\n\n  For example:\n\n  ```\n  /foo//bar/%2E%2E/ba%7A;bim =\u003e /foo//bar/../baz\n  ```\n\n  ```\n  /foo/bar;bar=chocolate/baz;baz=bim =\u003e /foo/bar/baz\n  ```\n\n\n  Requests intending to include a semicolon in the path should percent-encode\n  the semicolon.  In this case, the server will preserve the semicolon after the\n  decoding step.\n\n  For example:\n\n  ```\n  /foo//bar/%2E%2E/ba%7A%3Bbim =\u003e /foo//bar/../baz;bim\n  ```\n\n  If the request has malformed content, e.g., partially-formed percent-encoded\n  characters like '%A%B', an HTTP 400 (Bad Request) error will be returned.\n\n  If the request has invalid % encoded UTF-8 characters, the path will be\n  decoded as an ISO-8859-1 encoded string.\n\n2. Check the percent-decoded path for any relative path segments ('..' or\n   '.').\n\n  If one or more relative path segments are found, an HTTP 400 (Bad Request)\n  error will be returned.\n\n  For example, an error would be returned for any of the following paths:\n\n  ```\n  .\n  ..\n  /foo//bar/../baz\n  /foo//./bar/baz\n  ```\n  \n  The following paths would not be considered to contain relative paths:\n\n  ```\n  /foo//bar/baz\n  /foo//bar/.../baz\n  /foo//bar/a.b/baz\n  /foo//bar/a..b/baz\n  ```\n  \n3. Compact any repeated forward slash characters in a path.\n\n  For example:\n\n  ```\n  /foo//bar/baz =\u003e /foo/bar/baz\n  /foo/bar////baz =\u003e /foo/bar/baz\n  ```\n\nThe following example shows the result after normalization of a URI request\npath which includes repeated forward slash characters which have been\npercent-encoded:\n\n```\n/foo%2F%2Fbar/ba%7A =\u003e /foo/bar/baz\n```\n\n#### `add-context-handler`\n\n`add-context-handler` takes two arguments: `[base-path context-path]`.  The `base-path`\nargument is a URL string pointing to a location containing static resources which are\nmade accessible at the `context-path` URL prefix.\n\nFor example, to make your CSS files stored in the `resources/css` directory available\nat `/css`:\n\n```clj\n(defservice MyWebService\n   [[:WebserverService add-context-handler]]\n   ;; initialization\n   (init [this context]\n      (add-context-handler \"resources/css\" \"/css\")\n      context))\n```\n\nThere is also a three argument version of the function which takes these arguments:\n`[base-path context-path options]`, where the first two arguments are the\nsame as in the two argument version and `options` is a map containing five optional keys,\n`:server-id`, `:redirect-if-no-trailing-slash`, `:normalize-request-uri`, \n`:follow-links`, and `:context-listeners`.\n\nThe value stored in `:server-id` specifies which server\nto add the context handler to, similar to how it is done in `add-ring-handler`. Again, like\n`add-ring-handler`, if this key is absent or the two argument version is called, the context handler\nwill be added to the default server. Calling the two-argument version or leaving out `:server-id`\nwill not work in a multiserver set-up if no default server is specified.\n\nThe value stored in `:redirect-if-no-trailing-slash` is a boolean indicating whether or not\nto redirect when a request is made to this handler without a trailing slash, just like with\n`add-ring-handler`. Again, this defaults to false.\n\nThe value stored in `:normalize-request-uri` is a boolean indicating whether\nor not the request URI should be normalized before it is made available to the\nhandler.  See the [Request URI Normalization](#request-uri-normalization)\nsection for more information on the normalization process.\n\nThe value stored in `:follow-links` is a\nboolean indicating whether or not symbolic links\nshould be served. The service does NOT serve symbolic links by default.\n\nThe value stored in `:context-listeners` is a list of objects implementing the\n[ServletContextListener] (http://docs.oracle.com/javaee/7/api/javax/servlet/ServletContextListener.html)\ninterface. These listeners are registered with the context created for serving the\nstatic content and receive notifications about the lifecycle events in the context\nas defined in the ServletContextListener interface. Of particular interest is the\n`contextInitialized` event notification as it provides access to the configuration\nof the context through the methods defined in the [ServletContext]\n(http://docs.oracle.com/javaee/7/api/javax/servlet/ServletContext.html)\ninterface. This opens up wide possibilities for customizing the context - in an\nextreme case the context originally capable of serving just the static content can\nbe changed through this mechanism to a fully dynamic web application (in fact this\nvery mechanism is used in the [trapperkeeper-ruby]\n(https://github.com/puppetlabs/trapperkeeper-ruby) project to turn the context into\na container for hosting an arbitrary ruby rack application - see [here]\n(https://github.com/puppetlabs/trapperkeeper-ruby/blob/master/src/clojure/puppetlabs/trapperkeeper/services/rack_jetty/rack_jetty_service.clj)).\n\n#### `add-servlet-handler`\n\n`add-servlet-handler` takes two arguments: `[servlet path]`.  The `servlet` argument\nis a normal Java [Servlet](http://docs.oracle.com/javaee/7/api/javax/servlet/Servlet.html).\nThe `path` is the URL prefix at which the servlet will be registered.\n\nThere is also a three argument version of the function which takes these arguments:\n`[servlet path options]`, where the first two arguments are the same as\nin the two argument version and options is a map containing four optional keys,\n`:server-id`, `:redirect-if-no-trailing-slash`, `normalize-request-uri`, and\n`:servlet-init-params`.\n\nAs in `add-ring-handler`, `:server-id` specifies which server to add\nthe handler to. If `:server-id` is absent or the two-argument function is called, the servlet\nhandler will be added to the default server. Calling the two-argument version or leaving out\n`:server-id` will not work in a multiserver set-up if no default server is specified.\n\nThe value stored in `:redirect-if-no-trailing-slash` is a boolean indicating whether or not\nto redirect when a request is made to this handler without a trailing slash, just like with\n`add-ring-handler`. Again, this defaults to false.\n\nThe value stored in `:normalize-request-uri` is a boolean indicating whether\nor not the request URI should be normalized before it is made available to the\nhandler.  See the [Request URI Normalization](#request-uri-normalization)\nsection for more information on the normalization process.\n\nThe value stored at the `:servlet-init-params` key is a map of servlet init\nparameters.\n\nFor example, to host a servlet at `/my-app`:\n\n```clj\n(ns foo\n    ;; ...\n    (:import [bar.baz SomeServlet]))\n\n(defservice MyWebService\n  [[:WebserverService add-servlet-handler]]\n  ;; initialization\n  (init [this context]\n    (add-servlet-handler (SomeServlet. \"some config\") \"/my-app\")\n    context))\n```\n\nFor more information see the [example servlet app](examples/servlet_app).\n\n#### `add-websocket-handler`\n\nNOTE: Websockets support is currently an experimental feature; the\nAPI for websockets support may be subject to minor changes in a\nfuture release.\n\n`add-websocket-handler` takes two arguments: `[handlers path]`.\nThe `handlers` is a map of callbacks to invoke when handling a websocket session.\nThe `path` is the URL prefix where this websocket servlet will be registered.\n\nThe possible callbacks for the `handlers` map are:\n\n```clj\n{:on-connect (fn [ws])\n :on-error   (fn [ws error])\n :on-close   (fn [ws status-code reason])\n :on-text    (fn [ws text])\n :on-bytes   (fn [ws bytes offset len])}\n```\n\nQuerying data or sending messages over the websocket is supported by\nthe functions of WebSocketProtocol protocol from the\n`puppetlabs.experimental.websocket.client` namespace:\n\n```clj\n(connected? [this]\n  \"Returns a boolean indicating if the session is currently connected\")\n(send! [this msg]\n  \"Send a message to the websocket client\")\n(close! [this] [this code reason]\n  \"Close the websocket session\")\n(remote-addr [this]\n  \"Find the remote address of a websocket client\")\n(ssl? [this]\n  \"Returns a boolean indicating if the session was established by wss://\")\n(peer-certs [this]\n  \"Returns an array of X509Certs presented by the ssl peer, if any\")\n(request-path [this]\n  \"Returns the URI path used in the websocket upgrade request to the server\"))\n```\n\nFor example, to provide a simple websockets echo service as `/wsecho`:\n\n```clj\n(ns foo\n   (:require [puppetlabs.experimental.websockets.client :as ws-client]))\n\n(def echo-handlers\n  {:on-text (fn [ws text] (ws-client/send! ws text))})\n\n(defservice wsecho-webservice\n  [[:WebserverService add-websocket-handler]]\n  (init [this context]\n    (add-websocket-handler echo-handlers \"/wsecho\")\n    context))\n```\n\n#### `add-war-handler`\n\n`add-war-handler` takes two arguments: `[war path]`.\nThe `war` is the file path or the URL to a WAR file.\nThe `path` is the URL prefix at which the WAR will be registered.\n\nFor example, to host `resources/cas.war` WAR at `/cas`:\n\n```clj\n(defservice cas-webservice\n  [[:WebserverService add-war-handler]]\n  (init [this context]\n    (add-war-handler \"resources/cas.war\" \"/cas\")\n    context))\n```\n\nThere is also a three-argument version that takes these parameters:\n`[war path options]`. `options` is a map containing three optional\nkeys, `:server-id`, `:redirect-if-no-trailing-slash`, and\n`:normalize-request-uri`.\n\nAs with `add-ring-handler`,\nthis determines which server the handler is added to. If this key is absent or the two argument\nversion is called, the handler will be added to the default server. Calling\nthe two-argument version or leaving out `:server-id` will not work in a\nmultiserver set-up if no default server is specified.\n\nThe value stored in `:redirect-if-no-trailing-slash` is a boolean indicating whether or not\nto redirect when a request is made to this handler without a trailing slash, just like with\n`add-ring-handler`. Again, this defaults to false.\n\nThe value stored in `:normalize-request-uri` is a boolean indicating whether\nor not the request URI should be normalized before it is made available to the\nhandler.  See the [Request URI Normalization](#request-uri-normalization)\nsection for more information on the normalization process.\n\n#### `add-proxy-route`\n\n`add-proxy-route` is used to configure certain the server as a reverse proxy for\ncertain routes.  This function will accept two or three arguments: `[target path]`, or\n`[target path options]`.\n\n`path` is the URL prefix for requests that you wish to proxy.\n\n`target` is a map that controls how matching requests will be proxied; here are\nthe keys required in the `target` map:\n\n* `:host`: required; a string representing the host or IP to proxy requests to.\n* `:port`: required; an integer representing the port on the remote host that requests\n  should be proxied to.\n* `:path`: required; the URL prefix that should be prepended to all proxied requests.\n\n`options`, if provided, is a map containing optional configuration for the proxy\nroute:\n\n* `:scheme`: optional; legal values are `:orig`, `:http`, and `:https`.  If you\n  specify `:http` or `:https`, then all proxied requests will use the specified\n  scheme.  The default value is `:orig`, which means that proxied requests will\n  use the same scheme as the original request.\n* `:ssl-config`: optional; may be set to either `:use-server-config` (default) or\n  to a map containing the keys `:ssl-cert`, `:ssl-key`, and `:ssl-ca-cert`, as\n  well as the optional keys `:cipher-suites` and `:protocols`.  If\n  `:use-server-config`, then any proxied requests that use HTTPS will use the same\n  SSL context/configuration that the web server is configured with.  If you specify\n  a map, then the entries must point to the PEM files that should be used for the\n  SSL context.  These keys have the same meaning as they do for the SSL configuration\n  of the main web server.\n* `:rewrite-uri-callback-fn`: optional; a function to manipulate the rewritten target\n  URI (e.g. change the port, or even change the entire URI) before Jetty continues on\n  with the proxy. The function must accept two arguments, `[target-uri req]`. For more\n  information, see [below](#rewrite-uri-callback-fn).\n* `:callback-fn`: optional; a function to manipulate the request object (e.g.\n  to add additional headers) before Jetty continues on with the proxy. The\n  function must accept two arguments, `[proxy-req req]`. For more information,\n  see [below](#callback-fn).\n* `:failure-callback-fn`: optional; a function to manipulate the response object in case of failure.\n  The function must accept four arguments, `[req resp proxy-resp failure]`. For more information,\n  see [below](#failure-callback-fn).\n* `:request-buffer-size`: optional; an integer value to which to set the size\n  of the request buffer used by the HTTP Client. This allows HTTP requests with\n  very large cookies to go through, as a large cookie can cause the request\n  buffer to overflow unless the size is increased. The default is 4096 bytes.\n* `:follow-redirects`: optional; a boolean that indicates whether or not the HttpClient\n  created by a ProxyServlet should follow redirects. Defaults to `false`.\n* `:server-id`: optional; the id of the server to which to add the proxy handler. If absent,\n  the handler will be added to the default server. If the two argument version of this function\n  is called, the handler will also be added to the default server. Leaving out `:server-id` or calling\n  the two argument version of this function will not work in a multiserver set-up if no default server\n  is specified.\n* `:redirect-if-no-trailing-slash`: optional; a boolean indicating whether or not to redirect\n  when a request is made to this proxy route without a trailing slash, as with `add-ring-handler`.\n  Defaults to false.\n* `:idle-timeout`: optional; sets the maximum amount of time, measured in seconds, for the proxy to \n  wait for a response from the upstream server. If no response is received within the time\n  specified, then an HTTP 504 error is returned. If this option is not specified then a value\n  of 30 seconds is used.\n\nSimple example:\n\n```clj\n(defservice foo-service\n  [[:WebserverService add-proxy-route]]\n  (init [this context]\n    (add-proxy-route\n        {:host \"localhost\"\n         :port 10000\n         :path \"/bar\"}\n        \"/foo\")\n    context))\n```\n\nIn this example, all incoming requests with a prefix of `/foo` will be proxied\nto `localhost:10000`, with a prefix of `/bar`, using the same scheme (HTTP/HTTPS)\nthat the original request used, and using the SSL context of the main webserver.\n\nSo, e.g., an HTTPS request to the main webserver at `/foo/hello-world` would be\nproxied to `https://localhost:10000/bar/hello-world`.\n\nA slightly more complex example:\n\n```clj\n(defservice foo-service\n  [[:WebserverService add-proxy-route]]\n  (init [this context]\n    (add-proxy-route\n        {:host \"localhost\"\n         :port 10000\n         :path \"/bar\"}\n        \"/foo\"\n        {:scheme :https\n         :ssl-config {:ssl-cert    \"/tmp/cert.pem\"\n                      :ssl-key     \"/tmp/key.pem\"\n                      :ssl-ca-cert \"/tmp/ca.pem\"}})\n    context))\n```\n\nIn this example, all incoming requests with a prefix of `foo` will be proxied\nto `https://localhost:10000/bar`.  We'll proxy using HTTPS even if the original\nrequest was HTTP, and we'll use the three pem files in `/tmp` to configure the\nHTTPS client, regardless of the SSL configuration of the main web server.\n\n#####`:rewrite-uri-callback-fn`\n\nThis option lets you provide a function to manipulate the rewritten target URI. The\nfunction is called in the overridden implementation of\n[`rewriteURI`](http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/proxy/ProxyServlet.html#rewriteURI(javax.servlet.http.HttpServletRequest))\nmethod after the target URI is computed. It must take two arguments, `[target-uri req]`, where `target-uri` is a\n[`URI`](http://docs.oracle.com/javase/7/docs/api/java/net/URI.html)\nand `req` is an\n[`HttpServletRequest`](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html).\n`target-uri` will be modified and returned by the function.\n\nAn example with a rewrite URI callback function:\n\n```clj\n(defservice foo-service\n  [[:WebserverService add-proxy-route]]\n  (init [this context]\n    (add-proxy-route\n        {:host \"localhost\"\n         :port 10000\n         :path \"/bar\"}\n        \"/foo\"\n        {:rewrite-uri-callback-fn (fn [target-uri req]\n          (if-not (= \"GET\" (.getMethod req))\n            (URI. \"http://localhost:11111/errors/unsupported-method\")\n            target-uri))})\n    context))\n```\n\nIn this example, all incoming requests with a method other than `GET` will be proxied\nto `http://localhost:11111/errors/unsupported-method`.\n\n#####`:callback-fn`\n\nThis option lets you provide a function to manipulate the request object.  The\nfunction will be passed to the\n[`customizeProxyRequest`](http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/proxy/ProxyServlet.html#customizeProxyRequest%28org.eclipse.jetty.client.api.Request,%20javax.servlet.http.HttpServletRequest%29)\nmethod. It must take two arguments, `[proxy-req req]`, where `proxy-req` is a\n[`Request`](http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/client/api/Request.html)\nand `req` is an\n[`HttpServletRequest`](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html).\n`proxy-req` will be modified and returned by the function.\n\nAn example with a callback function:\n\n```clj\n(defservice foo-service\n  [[:WebserverService add-proxy-route]]\n  (init [this context]\n    (add-proxy-route\n        {:host \"localhost\"\n         :port 10000\n         :path \"/bar\"}\n        \"/foo\"\n        {:callback-fn (fn [proxy-req req]\n          (.header proxy-req \"x-example\" \"baz\"))})\n    context))\n```\n\nIn this example, all incoming requests with a prefix of `foo` will be proxied\nto `https://localhost:10000/bar`, using the same scheme (HTTP/HTTPS) that the\noriginal request used, and using the SSL context of the main webserver. In\naddition, a header `\"x-example\"` with the value `\"baz\"` will be added to the\nrequest before it is proxied, using the\n[`header`](http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/client/api/Request.html#header%28java.lang.String,%20java.lang.String%29)\nmethod.\n\n#####`:failure-callback-fn`\n\nThis option lets you provide a function to manipulate the response object in case of failure. It must take\nfour arguments, `[req resp proxy-resp failure]`, where `req` is the original\n[`HttpServletRequest`](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html),\n`resp` is an [`HttpServletResponse`](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletResponse.html),\n`proxy-req` a [`Response`](http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/client/api/Response.html)\nand `failure` is a [`Throwable`](http://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html) explaining the\ncause of the problem.\n`resp` may be modified, the function does not return any value.\n\nAn example with an on-failure function:\n\n```clj\n(defservice foo-service\n  [[:WebserverService add-proxy-route]]\n  (init [this context]\n    (add-proxy-route\n        {:host \"localhost\"\n         :port 10000\n         :path \"/bar\"}\n        \"/foo\"\n        {:failure-callback-fn (fn [req resp proxy-resp failure]\n          (.println (.getWriter resp) (str \"Proxying failed: \" (.getMessage failure))))})\n    context))\n```\n\nIn this example, in case of proxying failure the response body will be augmented by an error message explaining\nwhat the cause of the problem was.\n\n#### `override-webserver-settings!`\n\n`override-webserver-settings!` is used to override settings in the `webserver`\nsection of the webserver service's config file.  This function will accept one\nargument, `[overrides]`.  `overrides` is a map which should contain a\nkey/value pair for each setting to be overridden.  The name of the setting to\noverride should be expressed as a Clojure keyword.  For any setting expressed in\nthe service config which is not overridden, the setting value from the config\nwill be used.\n\nFor example, the webserver config may contain:\n\n```\nwebserver {\n    ssl-host:    0.0.0.0\n    ssl-port:    9001\n    ssl-cert:    mycert.pem\n    ssl-key:     mykey.pem\n    ssl-ca-cert: myca.pem\n}\n```\n\nOverrides may be supplied from the service using code like the following:\n\n```clj\n(defservice foo-service\n  [[:WebserverService override-webserver-settings!]]\n  (init [this context]\n    (override-webserver-settings!\n      {:ssl-port    9002\n       :ssl-cert    \"myoverriddencert.pem\"\n       :ssl-key     \"myoverriddenkey.pem\"})\n    context))\n```\n\nFor this example, the effective settings used during webserver startup would be:\n\n```clj\n{:ssl-host    \"0.0.0.0\"\n :ssl-port    9002\n :ssl-cert    \"myoverriddencert.pem\"\n :ssl-key     \"myoverriddenkey.pem\"\n :ssl-ca-cert \"myca.pem\"}\n```\n\nThe overridden webserver settings will be considered only at the point the\nwebserver is being started -- during the start lifecycle phase of the\nwebserver service.  For this reason, a call to this function must be made\nduring a service's init lifecycle phase in order for the overridden\nsettings to be considered.\n\nOnly one call from a service may be made to this function during application\nstartup.\n\nIf a call is made to this function after webserver startup or after another\ncall has already been made to this function (e.g., from other service),\na java.lang.IllegalStateException will be thrown.\n\nA three argument version is available which takes these parameters: `[server-id overrides]`.\n`server-id` is the id of the server for which you wish to override the settings. If the\ntwo argument version is called, they will be overridden for the default server. The one-argument\nversion of this function will not work in a multiserver set-up if no default server is specified.\n\n#### `get-registered-endpoints`\n\nThis function returns a map containing information on each URL endpoint\nregistered by the Jetty9 service on the default server. Each key in the map is a URL\nendpoint, with each value being an array of maps containing information on each handler\nregistered at that URL endpoint. The possible keys appearing in these maps are:\n\n* `:type`: The type of the registered endpoint. The possible types are `:context`,\n  `:ring`, `:servlet`, `:war`, and `:proxy`. Returned for every endpoint.\n* `:base-path`: The base-path of a context handler. Returned only for endpoints of\n  type `:context`.\n* `:context-listeners`: The context listeners for a context handler. Returned only\n  for endpoints of type `:context` that have context listeners.\n* `:servlet`: The servlet for a servlet handler. Only returned for endpoints of type\n  `:servlet`.\n* `:war-path`: The local path of the war registered by a war handler. Only returned\n  for endpoints of type `:war`.\n* `:target-host`: The targeted host of a proxy request. Only returned for endpoints\n  of type `:proxy`.\n* `:target-port`: The targeted port of a proxy request. Only returned for endpoints\n  of type `:proxy`.\n* `:target-path`: The targeted prefix of a proxy request. Only returned for endpoints\n  of type `:proxy`.\n\nThe schema for the various types of handler maps can be viewed [here](https://github.com/puppetlabs/trapperkeeper-webserver-jetty9/blob/master/src/puppetlabs/trapperkeeper/services/webserver/jetty9_core.clj#L71-L96).\n\nThere is also a version that takes one argument, `[server-id]`, which specifies which server\nfor which you want to pull the endpoints. If this parameter is absent, the endpoints will be\npulled for the default server. The no-argument version of this function will not work in a\nmultiserver set-up if no default server is specified.\n\n#### `log-registered-endpoints`\n\nThis function logs the data returned by `get-registered-endpoints` at the info level.\n\nThere is a version of this function that takes a single argument, `[server-id]`. This\nspecifies which server for which you want to log the endpoints. If this is absent,\nthe endpoints registered on the default server will be logged. The no-argument version\nof this function will not work in a multiserver set-up if no default server is specified.\n\n#### `join`\n\nThis function is not recommended for normal use, but is provided for compatibility\nwith the `ring-jetty-adapter`.  `ring-jetty-adapter/run-jetty`, by default,\ncalls `join` on the underlying Jetty server instance.  This allows your thread\nto block until Jetty shuts down.  This should not be necessary for normal\ntrapperkeeper usage, because trapperkeeper already blocks the main thread and\nwaits for a termination condition before allowing the process to exit.  However,\nif you do need this functionality for some reason, you can simply call `(join)`\nto cause your thread to wait for the Jetty server to shut down.\n\nThere is another version of this function that takes a single argument, `[server-id]`.\nThis is the id of the server you want to join. If this is not specified, then\nthe default server will be joined. The no-argument version of this function will not\nwork in a multi-server set-up if no default server is specified.\n\n### Service lifecycle phases\n\nThe Trapperkeeper service manipulates the Java Jetty code in the following ways during\nthese lifecycle phases.\n\n#### `init`\n\nA `ContextHandlerCollection` is created during the `init` lifecycle which allows for\nconsumers to use the `add-*-handler` and `add-proxy-route` functions,\nbut the Jetty server itself has not started yet. This allows the service\nconsumer to setup SSL keys and perform other operations needed before the server is started.\n\n#### `start`\n\nIn the start lifecycle phase the Jetty server object is created, the `ContextHandlerCollection` is added to it, and the server is then started. Adding handlers \nafter this phase should still work fine, but it is recommended that handlers be added \nduring the consuming service's `init` phase.\n\n## Webrouting Service\n\nThis project provides a secondary Webrouting Service, which in many cases\nis preferable for use over the Webserver Service. Documentation is available for it\n[here](doc/webrouting-service.md).\n\n## TrapperKeeper Webserver Service Test Utils\n\nThis project provides some utility code for testing. Documentation on these test utils\nis available [here](doc/test-utils.md).\n\n## Support\n\nWe use the [Trapperkeeper project on JIRA](https://tickets.puppetlabs.com/browse/TK)\nfor tickets on the Trapperkeeper Webserver Service, although Github issues are\nwelcome too.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Ftrapperkeeper-webserver-jetty9","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Ftrapperkeeper-webserver-jetty9","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Ftrapperkeeper-webserver-jetty9/lists"}