{"id":18655671,"url":"https://github.com/knotx/knotx-server-http","last_synced_at":"2026-04-27T16:31:12.978Z","repository":{"id":47259329,"uuid":"169749722","full_name":"Knotx/knotx-server-http","owner":"Knotx","description":"HTTP Server that handles all incoming HTTP requests and routes the traffic using OpenAPI specs","archived":false,"fork":false,"pushed_at":"2024-03-16T07:37:06.000Z","size":3933,"stargazers_count":0,"open_issues_count":7,"forks_count":2,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-01-14T23:47:05.491Z","etag":null,"topics":["http","netty","server"],"latest_commit_sha":null,"homepage":"https://knotx.io","language":"Java","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/Knotx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-02-08T14:48:59.000Z","updated_at":"2024-02-05T21:25:00.000Z","dependencies_parsed_at":"2024-03-21T20:49:01.509Z","dependency_job_id":null,"html_url":"https://github.com/Knotx/knotx-server-http","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Knotx/knotx-server-http","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-server-http","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-server-http/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-server-http/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-server-http/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Knotx","download_url":"https://codeload.github.com/Knotx/knotx-server-http/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-server-http/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32345802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["http","netty","server"],"created_at":"2024-11-07T07:19:42.729Z","updated_at":"2026-04-27T16:31:12.953Z","avatar_url":"https://github.com/Knotx.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://dev.azure.com/knotx/Knotx/_apis/build/status/Knotx.knotx-server-http?branchName=master)](https://dev.azure.com/knotx/Knotx/_build/latest?definitionId=8\u0026branchName=master)\n[![CodeFactor](https://www.codefactor.io/repository/github/knotx/knotx-server-http/badge)](https://www.codefactor.io/repository/github/knotx/knotx-server-http)\n[![codecov](https://codecov.io/gh/Knotx/knotx-server-http/branch/master/graph/badge.svg)](https://codecov.io/gh/Knotx/knotx-server-http)\n[![Gradle Status](https://gradleupdate.appspot.com/Knotx/knotx-server-http/status.svg)](https://gradleupdate.appspot.com/Knotx/knotx-server-http/status)\n\n# Knot.x HTTP Server\nServer is essentially a \"heart\" of Knot.x. It's scalable (vertically and horizontally), \nplugable (easy to extend), fault-tolerant \nand highly efficient reactive server based on [Vert.x](https://vertx.io/).\n\nLike any HTTP server, Knot.x HTTP Server allows you to define supported routes. Defining routes \nand security is done with [Open API 3](https://github.com/OAI/OpenAPI-Specification) standard.\n\nKnot.x Server enables plugging in custom behaviour for each supported route.\nEach defined [`path`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject)\nis processed by the chain of [Handlers](https://vertx.io/docs/apidocs/io/vertx/core/Handler.html)\nthat reacts on the request and is able to shape the response.\n\n![server flow](misc/server-flow.png)\n\n**Tree of content**  \n* [Modules](#modules)\n* [How does it work](#how-does-it-work)\n* [How to configure](#how-to-configure)\n  + [Http Server Options](#http-server-options)\n    - [Server Port Configuration](#server-port-configuration)\n  + [Dropping the requests](#dropping-the-requests)\n  + [Routing Specification](#routing-specification)\n  + [Routing Operations](#routing-operations)\n  + [Routing Security](#routing-security)\n    - [Example security setup](#example-security-setup)\n\n## Modules\nYou will find docs in the `README.md` files inside each of following modules:\n- [Server API](https://github.com/Knotx/knotx-server-http/tree/master/api) that defines contracts. \n- [Server core](https://github.com/Knotx/knotx-server-http/tree/master/core) that contains basic  \nhandlers and HTTP Server implementation.\n- [Common](https://github.com/Knotx/knotx-server-http/tree/master/common) contains reusable helper methods grouped into modules (e.g. [Knot.x Server Common Placeholders](https://github.com/Knotx/knotx-server-http/tree/master/common/placeholders)).\n\n## How does it work\nKnot.x HTTP Server is a [verticle](http://vertx.io/docs/apidocs/io/vertx/core/Verticle.html)\nthat listens for HTTP requests. It is responsible for handling the whole HTTP traffic that goes to \nthe Knot.x instance.\n\nOnce the HTTP request comes to the Server following actions are happening:\n- Server checks if there is a [routing path](#routing-specification) defined for the incoming request path\nand method. If no path supports this request, `404 Not Found` is returned in the response.\n- Server checks whether a [routing operation](#routing-operations) has been defined for the incoming request.\nIf no handlers are defined in the operations for this route, `501 Not Implemented` is returned in the response.\n- Handlers processing starts. In case of operation handler failure, [failure handlers](#handling-failures)\nare triggered.\n- Handling is continued until any Handler ends (completes) the response. If none does, \n`500 Internal Server Error` is returned.\n\n## How to configure\nTo run Knot.x HTTP Server, simply add an entry in the [`modules` configuration](https://github.com/Knotx/knotx-launcher#modules-configuration):\n\n```hocon\nmodules = {\n  server = \"io.knotx.server.KnotxServerVerticle\"\n}\n```\n\nDetails of the Knot.x HTTP Server can be configured with [`KnotxServerOptions`](/core/docs/asciidoc/dataobjects.adoc#knotxserveroptions)\nin the configuration file:\n```hocon\nconfig.server.options.config {\n  # options defined here\n}\n```\nMore details about the module configuration can be found in [Knot.x Launcher](https://github.com/Knotx/knotx-launcher#modules-configuration).\n\n### Http Server Options\nHTTP options such as port, connection windows size, default version of ALPN (HTTP/2, HTTP/1) etc. \ncan be configured with Vert.x [`HttpServerOptions`](http://vertx.io/docs/vertx-core/dataobjects.html#HttpServerOptions).\n\nE.g. following configuration specifies the port Server is listening at:\n```hocon\nconfig.server.options.config {\n  serverOptions {\n    port = 8080\n  }\n}\n```\n#### Server Port Configuration \nKnot.x HTTP Server port can also be specified by the system property `knotx.port` that takes \nprecedence over the value in the configuration file.\n```\njava -Dknotx.port=9999 ...\n```\n\n### Dropping the requests\nKnot.x Server implements the backpressure mechanism. It drops / rejects requests after exceeding a \ncertain number of requests at a time.\nIf Knot.x Server can NOT process incoming requests fast enough (the requests buffer limit has been reached), \nServer drops requests and responds with a configurable response code (by default `429, \"Too Many Requests\"`).\n\nDropping requests can be configured with [`DropRequestOptions`](core/docs/asciidoc/dataobjects.adoc#droprequestoptions)\n\nAfter the buffer slots are released, new requests will be accepted and finally processed.\n\n\u003e That solution prevent `OutOfMemoryError` errors when there are too many requests (e.g. during the peak hours). \nAdditionally response times should be more stable when system is under high stress.\n\n### Routing Specification\nKnot.x Routing is defined with [Open API 3](https://github.com/OAI/OpenAPI-Specification) standard. \n`routingSpecificationLocation` is the path to the YAML Open API specification.\nIt can be an absolute path, a local path or remote url (with `HTTP`).\n\n```hocon\nconfig.server.options.config {\n  routingSpecificationLocation = /openapi.yaml\n}\n```\n\n### Routing Operations\n[`Routing Operation`](core/docs/asciidoc/dataobjects.adoc#routingoperationoptions) \ndefines handlers and failure handlers involved in the processing of HTTP request for a specific\n[operation](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject)\ndefined in the [Routing Specification](#routing-specification) (linking is done\nby `operationId`):\n\n\u003e Open Api YAML config:\n```yaml\n...\npaths:\n  /example*:\n    get:\n      operationId: my-example-operation\n...\n```\n\u003e Routing Operations entry in Knot.x conf\n```hocon\nconfig.server.options.config.routingOperations = ${routingOperations} [\n  {\n    operationId = my-example-operation\n    handlers = [\n      # list of handlers that handles the request in chain\n    ]\n    failureHandlers = [\n      # list of failure handlers\n    ]\n  }\n]\n```\n\n#### Routing Handler\nRouting Handler is nothing else than a basic Vert.x [Handler](https://vertx.io/docs/apidocs/io/vertx/core/Handler.html) that operate on the [`RoutingContext`](https://vertx.io/docs/apidocs/io/vertx/ext/web/RoutingContext.html).\nYou may find more information about it in the [API docs](https://github.com/Knotx/knotx-server-http/tree/master/api#routing-handlers).\nEach `handler` is configured with [Routing Handler Options](/core/docs/asciidoc/dataobjects.adoc#routinghandleroptions).\n\n#### Routing Order\nKnot.x server makes use of the [`OpenAPI3RouterFactory`](https://vertx.io/docs/apidocs/io/vertx/ext/web/api/contract/openapi3/OpenAPI3RouterFactory.html) in order to combine OpenAPI routes specification with configured handlers. According to `OpenAPI3RouterFactory` docs, handlers are loaded in this order:\n\n\u003e 1. Body handler (Customizable with this#setBodyHandler(BodyHandler)\n\u003e 2. Custom global handlers configurable with this#addGlobalHandler(Handler)\n\u003e 3. Global security handlers defined in upper spec level\n\u003e 4. Operation specific security handlers\n\u003e 5. Generated validation handler\n\u003e 6. User handlers or \"Not implemented\" handler\n\nAlso, `operations` in the server are mounted in the definition order inside yaml specification.\n\n### Routing Security\nSecurity for each operation defined in the [Open API specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#security-requirement-object)\nis implemented in a form of [`AuthHandlers`](https://vertx.io/docs/apidocs/io/vertx/ext/web/handler/AuthHandler.html).\nIn order to add security for the operation, you need to implement [`AuthHandlerFactory`](https://github.com/Knotx/knotx-server-http/blob/master/api/src/main/java/io/knotx/server/api/security/AuthHandlerFactory.java)\nthat provides `AuthHandler` of a proper type.\n\n#### Example security setup\n\u003e Open Api YAML config:\n```yaml\n...\npaths:\n  /example*:\n    get:\n      operationId: my-example-operation\n      security:\n          - myExampleBasicAuth: []\n...\ncomponents:\n  securitySchemes:\n    myExampleBasicAuth:\n      type: http\n      scheme: basic\n```\n\n\u003e Routing Operations entry in Knot.x conf\n```hocon\nconfig.server.options.config.securityHandlers = [\n  {\n    schema = myExampleBasicAuth\n    factory = myBasicAuthHandlerFactory\n    config = {\n      # any config passed to the AuthHandler\n    }\n  }\n]\n```\n\nAlso, you need to implement and **register** [`AuthHandlerFactory`](api#creating-auth-handler).\nFor the example above:\n - `name` would be `myBasicAuthHandlerFactory`\n\n### Global Handlers\n[`Global Handlers`](core/docs/asciidoc/dataobjects.adoc#globalhandlers) \ndefines handlers that will be applied before any [`routing operation`](core/docs/asciidoc/dataobjects.adoc#routingoperationoptions).\n\nPlease note that you should not add a body handler inside that list. If you want to modify the \nbody use [`routing operation`](core/docs/asciidoc/dataobjects.adoc#routingoperationoptions) handlers.\n\n```hocon\nconfig.server.options.config.globalHandlers = [\n  {\n    name = myGlobalHandler\n    config {\n      // some configuration passed via factory to the handler\n    }\n  }\n]\n```\n\nEach `handler` is specified with [Routing Handler Options](/core/docs/asciidoc/dataobjects.adoc#routinghandleroptions).\n\n#### Access Logs\nTo log every request incoming to the Knot.x HTTP Server setup [`LoggerHandler`](https://vertx.io/docs/apidocs/io/vertx/reactivex/ext/web/handler/LoggerHandler.html)\nas a [`globalHandler`](#global-handlers). Use `loggerHandler` factory and [`Access Log Options`](core/docs/asciidoc/dataobjects.adoc#accesslogoptions)\nstructure in order to configure it to your needs.\n\n```hocon\nconfig.server.options.config.globalHandlers = [\n  {\n    name = loggerHandler\n    config {\n      immediate = true\n      format = DEFAULT\n    }\n  }\n]\n```\n\nBy default, access logs are logged to the `knotx-access.log` in the logs directory. To find more about\ndefault logger configuration, please see [Knot.x Launcher logback settings](https://github.com/Knotx/knotx-launcher#logback-settings).\n\nOf course you may also use `loggerHandler` factory to log access to only specific routes via \n[`routing operation`](core/docs/asciidoc/dataobjects.adoc#routingoperationoptions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknotx%2Fknotx-server-http","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknotx%2Fknotx-server-http","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknotx%2Fknotx-server-http/lists"}