# Web Clients — Local Brokers, Host Order, and `map.clients-to-backends`

This note explains how per-broker web-client port ranges are described in the
directory, how the **host order / host index** is derived from the directory
(no `hosts.txt` file is involved), and how `ClientsToPortsGenerator` produces the
`map.clients-to-backends` file consumed by a reverse proxy.

It is written against the broker example below and the code in
`com.goldencode.p2j.main.{BrokerDiscovery, Broker, ClientsToPortsGenerator,
HostsManager, WebClientsManager}`.

## 0. Two modes

`ClientsToPortsGenerator.generate(String host)` picks one of two modes based on
whether the directory's `brokers` container has any broker nodes:

| Mode | Condition | Hosts | Host index |
|------|-----------|-------|------------|
| **Broker mode** | `brokers` container is **non-empty** | one entry per ports-restricted broker | the broker's **position in the directory order** (loopback = 1, brokers = 2, 3, …) |
| **Local mode**  | `brokers` container is **empty** | a single host | always **1** |

In **local mode** the single host is the `host` argument passed to `generate`
(the actual representer of the local server, e.g. its LAN address
`192.168.100.3`), or `localhost` when no host is supplied. **No `hosts.txt` input
is required in either mode** — the host order comes entirely from the directory
(broker mode) or from the single host argument (local mode).

> **Host order is directory-based.** The host index is *not* stored in a file and
> is *not* an attribute on any node. In broker mode it is the enumeration order
> of the broker nodes under the `brokers` container; the FWD server's loopback is
> index `1` and brokers are `2, 3, …`. Because the generator and the running
> server both derive the index from that same ordered list, their indices agree
> by construction.

## 1. The directory data (broker mode)

A broker is a node under the `brokers` container (which itself lives under
`/server/<serverId>/`, e.g. `/server/default/`):

```xml
<node class="container" name="brokers">
  <node class="broker" name="broker1">
    <node-attribute name="account" value="sbi"/>
    <node-attribute name="broker_account" value="broker1_process"/>
    <node-attribute name="host" value="192.168.100.28"/>
    <node class="container" name="portsRange">
      <node class="string" name="namePrefix">
        <node-attribute name="value" value="client"/>
      </node>
      <node class="integer" name="from">
        <node-attribute name="value" value="7449"/>
      </node>
      <node class="integer" name="to">
        <node-attribute name="value" value="7459"/>
      </node>
    </node>
  </node>
</node>
```

The `broker` object-class (see `dir_schema.xml`) is **non-leaf** and carries:

| Attribute        | Mandatory | Multiple | Meaning |
|------------------|-----------|----------|---------|
| `host`           | yes       | no       | The host name / IP address on which this broker's client (agent) runs. This is the broker's **identity for host ordering**. |
| `broker_account` | yes       | no       | The FWD process account the broker client must authenticate as to register with the server. |
| `account`        | no        | yes      | The list of FWD user accounts served by this broker. |

The child `portsRange` container holds the **web-client port range** for this
broker:

| Node                  | Meaning |
|-----------------------|---------|
| `portsRange/from`     | First web-client port (inclusive). |
| `portsRange/to`       | Last web-client port (inclusive). |
| `portsRange/namePrefix` | **Not read per broker** — see the caveat in §6. |

In the example, `broker1` runs on `192.168.100.28` and owns the web-client port
range `7449..7459` (11 ports).

### How the directory data is read

`BrokerDiscovery.readBrokerConfigs(ds)`:

1. Locates the `brokers` container via `Utils.findDirectoryNodePath(ds,
   "brokers", "container", false)`.
2. Enumerates the broker child nodes with `ds.enumerateNodes(path)` and, **in
   that enumeration order**, builds a `LinkedHashMap<String, Broker>` (broker
   name → `Broker`). **This ordered map is what defines the host order** — see
   §2.
3. For each broker node, `getBroker(...)` reads the `account` / `broker_account`
   / `host` attributes, then reads the two port-range values **relative to the
   broker node** using `ConfigItem.RELATIVE_TO_PARENT`:

   ```java
   int from = ConfigItem.<Integer>createConfigItemOfType(
                 ConfigItem.CLIENT_PORT_RANGE_FROM, Type.RELATIVE_TO_PARENT)
             .setContainerNodeSearchPath("brokers/broker1/")   // "brokers/<name>/"
             .read(0);
   // ... same for CLIENT_PORT_RANGE_TO ("portsRange/to")
   ```

   `CLIENT_PORT_RANGE_FROM`/`_TO` have node name `portsRange/from` /
   `portsRange/to`, so the resolved directory path is
   `brokers/broker1/portsRange/from` and `…/to`.

4. The resulting `Broker` reports `isPortsRestricted()` as
   `(to > from) && (from > 0)`. For `broker1` that is
   `(7459 > 7449) && (7449 > 0)` → **true**. A broker whose range is absent or
   invalid is **not** ports-restricted: it still occupies a host index (§2) but
   produces no lines in the map.

## 2. Host order — derived from the broker enumeration order

There is no host-index file and no stored index attribute. In broker mode the
host index is the **position of a broker in the ordered broker list**:

* Index **1** is reserved for the FWD server's own loopback host
  (`localhost` / `127.0.0.1`). The server is always "host 1".
* **Every** broker node consumes the next index in the order it appears under the
  `brokers` container — the first broker → `2`, the second → `3`, and so on. This
  is true even for a broker that is not ports-restricted: it still takes its slot
  so that the numbering stays aligned with the runtime, which registers one host
  per broker regardless of its port configuration (§7).

So for the example (one broker, `broker1` on `192.168.100.28`):

```
index 1 : localhost / 127.0.0.1   (the FWD server)
index 2 : 192.168.100.28          (broker1, first broker node)
```

Add a `broker2` after `broker1` and it becomes index `3`, etc. The ordering is
the directory enumeration order — the same order `BrokerDiscovery` returns and
the same "well-defined host order" the comment in `BrokerManager.registerBroker`
refers to. **To renumber a host, reorder the broker nodes** in the directory.

Each broker declares a unique `host` (mandatory, single-valued), and
`BrokerManager` rejects a second broker that resolves to a host already claimed,
so the host → index mapping is one-to-one.

> **Design decision — count every broker.** The host index advances for *every*
> broker node, including brokers that are not ports-restricted, rather than only
> for the brokers that emit lines. This is deliberate, for consistency with the
> runtime: `BrokerManager.registerBroker` registers one host per broker
> (`HostsManager.addHost`) regardless of its port configuration, so a
> non-ports-restricted broker still consumes a host slot at runtime. Counting it
> in the generator too keeps the offline indices and the runtime indices in
> lockstep. The trade-off is that the position of *all* broker nodes affects the
> numbering — adding, removing, or reordering any broker shifts the indices of
> the brokers after it.

## 3. Mode selection in `generate(String host)`

```
generate(host):
  brokers = BrokerDiscovery.readBrokerConfigs(ds)
  if (!brokers.isEmpty()):
      → generateWithBrokerRanges(brokers, fileName)   # broker mode (directory-ordered)
  else:
      → local mode: single host = host or "localhost", at index 1
```

The switch is simply **whether any broker node exists**. (Note this differs from
an earlier draft that switched on "any broker is ports-restricted"; the mode is
now decided purely by the presence of broker nodes.)

## 4. Broker mode — `generateWithBrokerRanges`

The generator walks the brokers **in directory order**, advancing the host index
for every broker (starting at `1` for the server loopback, so the first broker
host is `2`), and emits lines only for ports-restricted brokers:

```
prefix    = resolvePrefix(...)            # see §6
hostIndex = 1                             # 1 == server loopback (localhost)

for (broker : brokers.values()) {         # directory enumeration order
   hostIndex++;                           # every broker takes a slot: 2, 3, ...
   if (!broker.isPortsRestricted()) continue;   # but only restricted ones emit lines

   for (port = broker.getFrom(); port <= broker.getTo(); port++) {
      name = getPortName(prefix, broker.getFrom(), hostIndex, port);
      write(name + "    " + broker.getHost() + ":" + port);
   }
}
```

The output file is `map.clients-to-backends` by default (the user may enter
another name at the prompt). Because the index comes from the broker order, there
is no `hosts.txt` lookup, creation, or write-back.

### Port name format

`getPortName` (shared by the generator and the runtime) is:

```
«prefix»-«hostIndex»-«port - from + 1»
```

i.e. `prefix`, the **host index**, and the **1-based offset of the port within
the range**, joined by hyphens.

## 5. Local mode — single host

When `brokers` is empty, the generator uses the **global**
`webClient/portsRange` (`from` / `to`, prompting and persisting them in the
directory if absent, exactly as before) and maps a **single host at index 1**:

```
localHost = (host == null || host.isEmpty()) ? "localhost" : host
for (port = from; port <= to; port++) {
   write(getPortName(prefix, from, 1, port) + "    " + localHost + ":" + port)
}
```

`host` is the `generate(...)` argument — supplied on the command line as the
optional second parameter (see §8). Use it to name the local server by the
address a reverse proxy must reach (e.g. `192.168.100.3`); omit it to fall back
to `localhost`.

## 6. Caveat — `namePrefix` under the broker node is ignored

`resolvePrefix(...)` reads `ConfigItem.PROXY_CLIENT_NAME_PREFIX`, which is a
`Type.WEB_CLIENT` item with node name `portsRange/namePrefix` — i.e. it resolves
to the **global** `webClient/portsRange/namePrefix`, *not* the
`portsRange/namePrefix` placed under the broker node.

Consequences:

* The `<node class="string" name="namePrefix" value="client"/>` inside
  `broker1/portsRange` in the example is **not consulted** by the generator.
* The prefix comes from `webClient/portsRange/namePrefix`; if that is empty the
  generator prompts for it (interactive) and defaults to `client` if nothing is
  entered.
* Only `portsRange/from` and `portsRange/to` are read per broker
  (`BrokerDiscovery` does not read a per-broker `namePrefix`).

If a per-broker prefix is intended, it would require reading
`brokers/<name>/portsRange/namePrefix` via a `RELATIVE_TO_PARENT` item in
`BrokerDiscovery`/`generateWithBrokerRanges`; today it is a single global value.

## 7. Worked examples

### Broker mode

Directory: a single ports-restricted broker `broker1` →
`host=192.168.100.28`, `from=7449`, `to=7459`, with `prefix=client`.

`broker1` is the first broker node, so its host order is `2` (index `1` is the
server loopback). The generator emits 11 lines:

```
client-2-1     192.168.100.28:7449
client-2-2     192.168.100.28:7450
client-2-3     192.168.100.28:7451
client-2-4     192.168.100.28:7452
client-2-5     192.168.100.28:7453
client-2-6     192.168.100.28:7454
client-2-7     192.168.100.28:7455
client-2-8     192.168.100.28:7456
client-2-9     192.168.100.28:7457
client-2-10    192.168.100.28:7458
client-2-11    192.168.100.28:7459
```

The left column is the proxy **route name**; the right column is the **backend**
the reverse proxy forwards that route to. If a `broker2` were added next, it
would produce `client-3-*` lines for its own host and range.

### Local mode

No brokers configured, global `webClient/portsRange` = `7449..7459`,
`prefix=client`, and the generator invoked with host `192.168.100.3`. The single
host is index `1`:

```
client-1-1     192.168.100.3:7449
client-1-2     192.168.100.3:7450
...
client-1-11    192.168.100.3:7459
```

Invoked with no host argument, the backend column would read `localhost:74xx`.

## 8. Command line

```
java com.goldencode.p2j.main.ClientsToPortsGenerator <directory.xml> [host]
```

* `<directory.xml>` — required; the directory the brokers / webClient config is
  read from.
* `[host]` — optional; the local-server host for **local mode** (defaults to
  `localhost`). **Ignored in broker mode**, where hosts come from the broker
  nodes. There is no `hosts.txt` argument.

## 9. The runtime side — the same order, no second source of truth

The generated `map.clients-to-backends` only routes correctly if the **host
index the proxy was configured with equals the host index the running server
uses**. Both sides derive that index from the **same directory data**, so they
agree by construction:

* `HostsManager` pins the server loopback at construction: `localhost → 1`,
  `127.0.0.1 → 1`, and the host counter starts at `1`.
* As brokers register (`BrokerManager.registerBroker` → `HostsManager.addHost`),
  each host is assigned `broker.getIndex() + 1` — i.e. its **directory position**
  (`BrokerDiscovery` sets `index = i + 1`), not a running registration-time
  counter. Keying the index off the directory position is what keeps the runtime
  aligned with the generator regardless of the order in which brokers actually
  register, or whether some brokers are skipped.
* `HostsManager.getPortName(prefix, from, host, port)` looks up that host's index
  directly by the `host` literal (`hosts.get(host)`) — **no DNS resolution at
  route-name time** — and calls the same `ClientsToPortsGenerator.getPortName(...)`.
  `WebClientsManager` uses this to build the proxy web-root for a web client.

```
 directory `brokers` order ──► host index ─┬─► generator: "client-2-7"  (map.clients-to-backends)
                                           └─► runtime  : "client-2-7"  (proxy web-root)
```

* **Local mode / single-host**: the host is index `1` on both sides; nothing to
  diverge.
* **Broker mode / multiple hosts**: the index is the broker's position in the
  directory order on both sides. Reordering the broker nodes (or the order in
  which brokers are expected to register) changes the index consistently for the
  generator and the server, so the proxy map and the runtime stay aligned without
  a flat file.

### Host literal form

A broker's `host` attribute is used verbatim as its identity. The running server
keys the host index by that exact literal: `HostsManager.addHost` stores the
index under the registered `host` string, and `getPortName` looks it up by the
same string (`hosts.get(host)`) — there is **no DNS resolution at route-name
time**. The host registered (`BrokerManager.registerBroker`) and the host used to
build the route name (`WebClientsManager`) both originate from the broker's
`host` config value, so they match by construction. Keep the `host` literal in a
single, consistent form across the directory and any proxy configuration derived
from these route names — a different spelling of the same address (e.g. a DNS
name vs. its IP) is treated as a distinct host because the lookup is now purely
string-keyed.

## 10. Summary

1. `generate(host)` runs **broker mode** when the `brokers` container has any
   broker nodes, **local mode** otherwise. Neither mode reads a `hosts.txt` file.
2. **Broker mode**: each broker node declares its `host`, `broker_account`, and a
   `portsRange/{from,to}`. The **host index is the broker's position in the
   directory order** — loopback `1`, brokers `2, 3, …`, counting every broker.
   Ports-restricted brokers emit `«prefix»-«hostIndex»-«offset»  «host»:«port»`
   lines into `map.clients-to-backends`.
3. **Local mode**: a single host (the `host` argument, or `localhost`) is mapped
   at index `1` using the global `webClient/portsRange`.
4. The running server (`HostsManager`) assigns indices from the same ordered
   broker registrations (loopback pinned to `1`), so the offline-generated proxy
   map and the runtime web-roots agree by construction.