From ea755c6ae3997e0964a02bba4892d965411cc171 Mon Sep 17 00:00:00 2001
From: Jiri Kozel <jirik@users.noreply.github.com>
Date: Tue, 26 Sep 2023 14:41:47 +0200
Subject: [PATCH] Document X-Forwarded-Proto -Host HTTP headers

---
 CHANGELOG.md        |  4 ++--
 doc/client-proxy.md | 26 +++++++++++++++++---------
 doc/rest.md         |  6 ++++--
 3 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 055f46c71..83d67099f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,7 +15,7 @@
 - [#765](https://github.com/LayerManager/layman/issues/765) Remove `authn.txt` files from workspace directories. The same information as in `authn.txt` files is saved in prime DB schema.
 - [#868](https://github.com/LayerManager/layman/issues/868) Fill table `map_layer` with relations between maps and [internal layers](doc/models.md#internal-map-layer) (layers published on this Layman instance). Relations to [external layers](doc/models.md#internal-map-layer) (layers of other servers) are not imported into the table.
 ### Changes
-- [#868](https://github.com/LayerManager/layman/issues/868) Responses to many requests respects [HTTP header `X-Forwarded-Prefix`](doc/client-proxy.md#x-forwarded-prefix-http-header) of the request. Those requests are:
+- [#868](https://github.com/LayerManager/layman/issues/868) Responses to many requests respect [HTTP X-Forwarded headers](doc/client-proxy.md#x-forwarded-http-headers) of the request. Those requests are:
   - GET [Publications](doc/rest.md#get-publications), [Layers](doc/rest.md#get-layers), [Workspace Layers](doc/rest.md#get-workspace-layers), [Maps](doc/rest.md#get-maps), and [Workspace Maps](doc/rest.md#get-workspace-maps)
   - [GET](doc/rest.md#get-workspace-layer), [PATCH](doc/rest.md#patch-workspace-layer), and [DELETE](doc/rest.md#delete-workspace-layer) Workspace Layer
   - [GET](doc/rest.md#get-workspace-map), [PATCH](doc/rest.md#patch-workspace-map), and [DELETE](doc/rest.md#delete-workspace-map) Workspace Map
@@ -23,7 +23,7 @@
   - [POST](doc/rest.md#post-workspace-layers) and [DELETE](doc/rest.md#delete-workspace-layers) Workspace Layers
   - [POST](doc/rest.md#post-workspace-maps) and [DELETE](doc/rest.md#delete-workspace-maps) Workspace Maps
   - requests to [WMS](doc/endpoints.md#web-map-service) and [WFS](doc/endpoints.md#web-feature-service) endpoints
-- [#868](https://github.com/LayerManager/layman/issues/868) Responses to [GET Workspace Layer Metadata Comparison](doc/rest.md#get-workspace-layer-metadata-comparison) and [GET Workspace Map Metadata Comparison](doc/rest.md#get-workspace-map-metadata-comparison) do not respect [HTTP header `X-Forwarded-Prefix`](doc/client-proxy.md#x-forwarded-prefix-http-header) of the request intentionally, in order to keep URLs in canonical form.
+- [#868](https://github.com/LayerManager/layman/issues/868) Responses to [GET Workspace Layer Metadata Comparison](doc/rest.md#get-workspace-layer-metadata-comparison) and [GET Workspace Map Metadata Comparison](doc/rest.md#get-workspace-map-metadata-comparison) do not respect [HTTP X-Forwarded headers](doc/client-proxy.md#x-forwarded-http-headers) of the request intentionally, in order to keep URLs in canonical form.
 - [#868](https://github.com/LayerManager/layman/issues/868) Relations between map and [internal layers](doc/models.md#internal-map-layer) are updated in `map_layer` table when calling [POST Workspace Maps](doc/rest.md#post-workspace-maps), [PATCH Workspace Map](doc/rest.md#patch-workspace-map), [DELETE Workspace Map](doc/rest.md#delete-workspace-map), and [DELETE Workspace Maps](doc/rest.md#delete-workspace-maps).
 - [#927](https://github.com/LayerManager/layman/issues/927) Send styles to GeoServer with [`raw`](https://docs.geoserver.org/2.21.x/en/user/rest/api/styles.html#raw) param set to `True`.
 - [#880](https://github.com/LayerManager/layman/issues/880) Use Docker Compose v2 (`docker compose`) in Makefile without `compatibility` flag and remove `Makefile_docker-compose_v1` file. Docker containers are named according to Docker Compose v2 and may have different name after upgrade.
diff --git a/doc/client-proxy.md b/doc/client-proxy.md
index 9a3e8b8b2..486307ff6 100644
--- a/doc/client-proxy.md
+++ b/doc/client-proxy.md
@@ -19,13 +19,21 @@ Imagine request e.g. to [GET Publications](rest.md#get-publications) sent throug
 ]
 ```
 
-By default, Layman will not adjust URLs in its response to contain also URL path prefix of the client proxy (`/layman-proxy` in above example). If you prefer to adjust URLs in Layman responses to contain also URL path prefix of the client proxy, you need to send also `X-Forwarded-Prefix` HTTP header with the request.
+By default, Layman will not adjust URLs in its response to contain also URL path prefix of the client proxy (`/layman-proxy` in above example). If you prefer to adjust URLs in Layman responses to contain also URL path prefix of the client proxy (or even host and protocol), you need to send also [X-Forwarded HTTP headers](#x-forwarded-http-headers) with the request.
 
-## X-Forwarded-Prefix HTTP header
+## X-Forwarded HTTP headers
 
-The value of the `X-Forwarded-Prefix` HTTP header will be used as prefix in some URL paths of Layman response and is required to match regular expression `^(?:/[a-z0-9_-]+)*$`.
+Layman supports three optional X-Forwarded HTTP headers, whose values will be used in some URLs in Layman responses:
+- `X-Forwarded-Proto`: The value will be used as protocol in some URLs, and it is required to be `http` or `https`.
+- `X-Forwarded-Host`: The value will be used as host in some URLs, and it is required to match regular expression `^(?=.{1,253}\.?$)(?:(?!-|[^.]+_)[a-z0-9-_]{1,63}(?<!-)(?:\.|$))+$`.
+- `X-Forwarded-Prefix`: The value will be used as prefix in some URL paths, and it is required to match regular expression `^(?:/[a-z0-9_-]+)*$`.
 
-For example, if you send request to `/layman-client-proxy/rest/publications` with HTTP header `X-Forwarded-Prefix=/layman-client-proxy` then response will change to
+For example, consider there is layman running at `https://enjoychallenge.tech/rest` and client proxy running at `https://laymanproxy.com/layman-client-proxy`. If you send request to your Layman proxy `https://laymanproxy.com/layman-client-proxy/rest/publications` with HTTP headers
+```
+X-Forwarded-Host=laymanproxy.com
+X-Forwarded-Prefix=/layman-client-proxy
+```
+then response will change to
 
 ```json
 [
@@ -33,14 +41,14 @@ For example, if you send request to `/layman-client-proxy/rest/publications` wit
     "workspace": "my_workspace",
     "publication_type": "layer",
     "name": "my_layer",
-    "url": "https://mylaymandomain.com/layman-client-proxy/rest/publications",
+    "url": "https://laymanproxy.com/layman-client-proxy/rest/publications",
     ...
   },
   ...
 ]
 ```
 
-Currently, value of `X-Forwarded-Prefix` affects following URLs:
+Currently, value of X-Forwarded headers affects following URLs:
 * [GET Publications](rest.md#get-publications)
   * `url` key
 * [GET Layers](rest.md#get-layers)
@@ -69,7 +77,7 @@ Currently, value of `X-Forwarded-Prefix` affects following URLs:
     * `protocol`.`url` key
     * each `legends` key if its HTTP protocol and netloc corresponds with `url` or `protocol`.`url`
     * `style` key if its HTTP protocol and netloc corresponds with `url` or `protocol`.`url`
-  * NOTE: If client proxy prefix was used in URLs in uploaded file, then such prefix is also replaced with prefix according to `X-Forwarded-Prefix` header value. Such prefix is removed for requests without `X-Forwarded-Prefix` header.
+  * NOTE: If client proxy protocol, host, or URL path prefix was used in URLs in uploaded file, then such values are also replaced with values according to X-Forwarded header values. Default values are used for requests without X-Forwarded headers (protocol is the one from [LAYMAN_CLIENT_PUBLIC_URL](env-settings.md#layman_client_public_url), host is [LAYMAN_PROXY_SERVER_NAME](env-settings.md#layman_proxy_server_name), and path prefix is empty string).
 * [POST Workspace Layers](rest.md#post-workspace-layers)
   * `url` key
 * [DELETE Workspace Layer](rest.md#delete-workspace-layer)
@@ -95,11 +103,11 @@ Currently, value of `X-Forwarded-Prefix` affects following URLs:
   * `thumbnail`.`url` key
   * `metadata`.`comparison_url` key
 * [OGC endpoints](endpoints.md)
-  * Headers `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-For`, `X-Forwarded-Path`, `Forwarded` and `Host` are ignored
+  * Headers `X-Forwarded-For`, `X-Forwarded-Path`, `Forwarded` and `Host` are ignored
   * [WMS endpoints](endpoints.md#web-map-service)
     * all requests URLs
     * all legend URLs
   * [WFS endpoints](endpoints.md#web-feature-service)
     * all operations URLs
 
-Value of `X-Forwarded-Prefix` does not affects response values of [GET Workspace Layer Metadata Comparison](rest.md#get-workspace-layer-metadata-comparison) and [GET Workspace Map Metadata Comparison](rest.md#get-workspace-map-metadata-comparison).
+Values of X-Forwarded headers does not affect response values of [GET Workspace Layer Metadata Comparison](rest.md#get-workspace-layer-metadata-comparison) and [GET Workspace Map Metadata Comparison](rest.md#get-workspace-map-metadata-comparison).
diff --git a/doc/rest.md b/doc/rest.md
index 1d7ecee85..e6047b4e7 100644
--- a/doc/rest.md
+++ b/doc/rest.md
@@ -578,7 +578,9 @@ Content-Type: `multipart/form-data`
 Body parameters:
 - **file**, JSON file
    - must be valid against [map-composition schema](https://github.com/hslayers/hslayers-ng/wiki/Composition-schema)
-   - URLs of [internal layers](models.md#internal-map-layer) may contain [client-proxy prefix](client-proxy.md)
+   - layer is considered [internal](models.md#internal-map-layer) if
+     - its URL points to the Layman instance (with or without client-proxy URL path prefix),
+     - or its URL protocol and its URL host corresponds with [X-Forwarded headers](client-proxy.md#x-forwarded-http-headers) (with or without client-proxy URL path prefix)
 - *name*, string
    - computer-friendly identifier of the map
    - must be unique among all maps of one workspace
@@ -739,7 +741,7 @@ Notice that some JSON properties are automatically updated by layman, so file ob
    - **email** set to email of the owner, or empty string if not known
    - other properties will be deleted
 - **groups** are removed
-- [some layer URLs](client-proxy.md#x-forwarded-prefix-http-header) according to `X-Forwarded-Prefix` header
+- [some layer URLs](client-proxy.md#x-forwarded-http-headers) according to X-Forwarded HTTP headers
 
 #### Request
 No action parameters.