1/**
2 * Network addresses for locating cluster runners. A `RunnerAddress` stores the
3 * host and port for a runner and provides schema support, structural equality,
4 * hashing, Node.js inspection, and a stable primary key formatted from the host
5 * and port.
6 *
7 * @stability unstable
8 * @since 4.0.0
9 */
10import * as Equal from "../Equal.ts"
11import * as Hash from "../Hash.ts"
12import { NodeInspectSymbol } from "../Inspectable.ts"
13import * as PrimaryKey from "../PrimaryKey.ts"
14import * as Schema from "../Schema.ts"
15
16const TypeId = "~effect/cluster/RunnerAddress"
17
18/**
19 * Represents the network address of a cluster runner, identified by host and
20 * port.
21 *
22 * **When to use**
23 *
24 * Use to represent the host and port that identify a runner in cluster routing,
25 * registration, and health checks.
26 *
27 * @stability unstable
28 * @category models
29 * @since 4.0.0
30 */
31export class RunnerAddress extends Schema.Class<RunnerAddress>(TypeId)({
32 host: Schema.String,
33 port: Schema.Int
34}) {
35 /**
36 * Marks this value as a cluster runner address for runtime guards.
37 *
38 * @stability unstable
39 * @since 4.0.0
40 */
41 readonly [TypeId] = TypeId;
42
43 /**
44 * Compares runner addresses by host and port.
45 *
46 * @stability unstable
47 * @since 4.0.0
48 */
49 [Equal.symbol](that: RunnerAddress): boolean {
50 return this.host === that.host && this.port === that.port
51 }
52
53 /**
54 * Computes a structural hash from the host and port.
55 *
56 * @stability unstable
57 * @since 4.0.0
58 */
59 [Hash.symbol]() {
60 return Hash.string(`${this.host}:${this.port}`)
61 }
62
63 /**
64 * Stable primary key used to identify the runner address.
65 *
66 * @stability unstable
67 * @since 4.0.0
68 */
69 [PrimaryKey.symbol](): string {
70 return `${this.host}:${this.port}`
71 }
72
73 /**
74 * Formats the runner address with its host and port.
75 *
76 * @stability unstable
77 * @since 4.0.0
78 */
79 override toString(): string {
80 return `RunnerAddress(${this.host}:${this.port})`
81 }
82
83 /**
84 * Formats the runner address for Node.js inspection.
85 *
86 * @stability unstable
87 * @since 4.0.0
88 */
89 [NodeInspectSymbol](): string {
90 return this.toString()
91 }
92}
93
94/**
95 * Constructs a `RunnerAddress` from a host and port.
96 *
97 * **When to use**
98 *
99 * Use to create the stable network identity for a cluster runner when
100 * configuring sharding, registering runner metadata, or targeting a runner by
101 * host and port.
102 *
103 * **Details**
104 *
105 * The returned `RunnerAddress` stores the supplied `host` and `port`. Equality,
106 * hashing, and the primary key use both fields, with the primary key formatted
107 * as `host:port`.
108 *
109 * **Gotchas**
110 *
111 * `make` does not normalize the host. Pass the host string exactly as the
112 * cluster routing and storage layers should identify it.
113 *
114 * @see {@link RunnerAddress} for the constructed address type and its equality, hashing, primary-key, and formatting behavior
115 *
116 * @stability unstable
117 * @category constructors
118 * @since 4.0.0
119 */
120export const make = (host: string, port: number): RunnerAddress =>
121 new RunnerAddress({ host, port }, { disableChecks: true })