{"id":13564740,"url":"https://github.com/abiosoft/caddy-named-routes","last_synced_at":"2025-04-11T00:31:53.117Z","repository":{"id":44135841,"uuid":"267630252","full_name":"abiosoft/caddy-named-routes","owner":"abiosoft","description":"named routes support for Caddy v2","archived":false,"fork":false,"pushed_at":"2021-05-26T09:16:24.000Z","size":61,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T21:13:44.777Z","etag":null,"topics":["caddy","caddy-module","caddyserver","http-routes"],"latest_commit_sha":null,"homepage":"","language":"Go","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/abiosoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-28T15:44:29.000Z","updated_at":"2024-08-09T20:44:30.000Z","dependencies_parsed_at":"2022-08-03T04:30:19.098Z","dependency_job_id":null,"html_url":"https://github.com/abiosoft/caddy-named-routes","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-named-routes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-named-routes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-named-routes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-named-routes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abiosoft","download_url":"https://codeload.github.com/abiosoft/caddy-named-routes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322247,"owners_count":21084334,"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":["caddy","caddy-module","caddyserver","http-routes"],"created_at":"2024-08-01T13:01:35.269Z","updated_at":"2025-04-11T00:31:53.074Z","avatar_url":"https://github.com/abiosoft.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# caddy-named-routes\n\nnamed routes is a Caddy v2 module for creating reusable named http routes.\n\n## Installation\n\n```\nxcaddy build v2.4.1 \\\n    --with github.com/abiosoft/caddy-named-routes\n```\n\n## Usage\n\nNamed route is only currently limited to Caddy API and not available for the Caddyfile.\n\n```jsonc\n{\n  \"app\": {\n    // define named routes\n    \"named_routes\": {\n      // the name for the route\n      \"\u003croute name\u003e\": [\n        // ... list of http routes\n      ]\n    },\n\n    // use the routes in the http handler\n    \"http\": {\n      \"servers\": {\n        \"srv0\": {\n          \"routes\": [\n            {\n              \"handle\": {\n                \"handler\": \"named_route\",\n                \"name\": \"\u003croute name\u003e\"\n              }\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\n## Why?\n\nCaddy's API is simple enough. What is this unnecessary complexity?\n\n### The Problem\n\nCaddy's configuration API is flexible and gives more control than the Caddyfile.\nHowever, composing http routes can get easily messy and unclear if you have many of them.\n\nConsider the following YAML config snippet for the configuration of two reverse proxies and a static file server. The average use case cannot get any simpler.\n\n**Note:** even though YAML is used here, Caddy's native configuration language is JSON. You need [config adapters](https://caddyserver.com/docs/config-adapters#known-config-adapters) for other than JSON.\n\n```yaml\nhttp:\n  servers:\n    default:\n      routes:\n        - match:\n            - host: [localhost] # other global conditions\n          handle:\n            - handler: subroute\n              routes:\n                # reverse proxy to API\n                - match:\n                    - path: [/api/*]\n                  handle:\n                    # strip prefix before reverse proxy\n                    - handler: rewrite\n                      strip_path_prefix: /api\n                    - handler: subroute\n                      routes:\n                        # API v2\n                        - match:\n                            - header:\n                                X-API-Version: [v2]\n                          handle:\n                            - handler: reverse_proxy\n                              upstreams:\n                                - dial: localhost:8080\n                        # API legacy\n                        - handle:\n                            - handler: reverse_proxy\n                              upstreams:\n                                - dial: localhost:8888\n            # blog\n            - handler: file_server\n              root: /home/blog/static\n            # fallback handler\n            - handler: static_response\n              status_code: \"404\"\n```\n\nThis is still relatively readable thanks to the comments and the simple use case. Now imagine a more complex structure and even worse; imagine the complex structure as a JSON config while bearing in mind pure JSON does not support comments.\n\n### The Alternative\n\nThe following is a composition of same YAML config with named routes.\n\n```yaml\nhttp:\n  servers:\n    default:\n      routes:\n        - match:\n            - host: [localhost] # other global conditions\n          handle:\n            # api\n            - handler: named_route\n              name: api\n            # blog\n            - handler: file_server\n              root: /home/blog/static\n            # fallback handler\n            - handler: static_response\n              status_code: \"404\"\n\nnamed_routes:\n  api:\n    - match:\n        - path: [/api/*]\n      handle:\n        # strip prefix before reverse proxy\n        - handler: rewrite\n          strip_path_prefix: /api\n        # attempt v2\n        - handler: named_route\n          name: api.v2\n        # otherwise fall back to legacy\n        - handler: named_route\n          name: api.legacy\n\n  api.v2:\n    - match:\n        header:\n          X-API-Version: [v2]\n      handle:\n        - handler: reverse_proxy\n          upstreams:\n            - dial: localhost:8080\n\n  api.legacy:\n    - handle:\n        - handler: reverse_proxy\n          upstreams:\n            - dial: localhost:8888\n```\n\nEven though the latter config is 10 lines longer, it looks cleaner and more readable.\n\n## License\n\nApache 2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabiosoft%2Fcaddy-named-routes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabiosoft%2Fcaddy-named-routes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabiosoft%2Fcaddy-named-routes/lists"}