@huaweidevtools/aishell-dsh-deploy 0.0.19 → 0.0.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,174 @@
1
+ /**
2
+ * Reading the account as the three things an architecture diagram shows.
3
+ *
4
+ * ## The three layers, and why they are separate
5
+ *
6
+ * A network diagram is not one graph. It is three, and a reader looks at each
7
+ * for a different question:
8
+ *
9
+ * 1. **Placement** — where a thing lives. A server is in a subnet, a subnet is
10
+ * in a VPC. This is drawn as nesting: the box is inside the other box.
11
+ * 2. **Attachment** — what hangs off a thing. An EIP belongs to a load
12
+ * balancer, a disk belongs to a server, a CCE node runs on a server. This
13
+ * is also nesting, for the same reason: it is the same kind of fact, and a
14
+ * line would say "related" where the truth is "part of".
15
+ * 3. **Policy** — whether traffic may flow. A security group admits another
16
+ * security group on a port. This is the only layer that is genuinely an
17
+ * edge, and the only one where direction and port carry meaning.
18
+ *
19
+ * A security group is NOT a fourth kind of node. It is a property of the thing
20
+ * it guards — drawn inside that thing's box — and separately a vertex of the
21
+ * policy graph. Drawing `server → security-group` as a line says the two are
22
+ * peers, which is false, and loses the real edges between groups entirely.
23
+ *
24
+ * @module @huaweidevtools/aishell-dsh-deploy/account-view
25
+ */
26
+ import type { InventoryResource } from './existing-topology.ts';
27
+ /** One resource as the inventory reports it. */
28
+ export type AccountResource = InventoryResource;
29
+ /** A security group's rule that admits traffic from another security group. */
30
+ export interface PolicyEdge {
31
+ /** The group doing the admitting. */
32
+ readonly to: string;
33
+ /** The group whose members are admitted. */
34
+ readonly from: string;
35
+ /** `ingress` or `egress`, as the provider reports it. */
36
+ readonly direction: string;
37
+ /** `tcp`, `udp`, `icmp` or `any`. */
38
+ readonly protocol: string;
39
+ /** The port range, or `undefined` for all ports. */
40
+ readonly ports: string | undefined;
41
+ }
42
+ /** The three layers, resolved. */
43
+ export interface AccountView {
44
+ /** Resource id → the id of the box it is drawn inside. */
45
+ readonly parentOf: ReadonlyMap<string, string>;
46
+ /** Resource id → the security group names that guard it. */
47
+ readonly guardsOf: ReadonlyMap<string, readonly string[]>;
48
+ /** The policy edges between groups, deduplicated. */
49
+ readonly policies: readonly PolicyEdge[];
50
+ /** Groups that take part in a policy edge, and so belong in the policy band. */
51
+ readonly policyGroups: ReadonlySet<string>;
52
+ }
53
+ /**
54
+ * How specifically an attribute names a container, 0 for none.
55
+ *
56
+ * @param attribute - a dotted property path.
57
+ * @returns the rank, higher being more specific.
58
+ */
59
+ export declare function nestRank(attribute: string): number;
60
+ /**
61
+ * Whether an attribute names a security group.
62
+ *
63
+ * @param attribute - a dotted property path.
64
+ * @returns whether it does.
65
+ */
66
+ export declare function isGuardAttribute(attribute: string): boolean;
67
+ /**
68
+ * Read the placement and attachment layer.
69
+ *
70
+ * @param resources - the account's resources.
71
+ * @returns resource id → the id of its container.
72
+ */
73
+ export declare function containment(resources: readonly AccountResource[]): Map<string, string>;
74
+ /**
75
+ * Read which security groups guard each resource.
76
+ *
77
+ * @param resources - the account's resources.
78
+ * @returns resource id → the group NAMES, sorted so two runs agree.
79
+ */
80
+ export declare function guards(resources: readonly AccountResource[]): Map<string, string[]>;
81
+ /**
82
+ * The resources that use each security group.
83
+ *
84
+ * ## Why this is worth showing
85
+ *
86
+ * A group's rules say what it admits; its users say whether it matters. On a
87
+ * live account 13 groups exist and only 6 are used by anything — and one of
88
+ * those is used by three resources. A reader who has to open each group to find
89
+ * out whether it is live cannot tell a housekeeping leftover from the group
90
+ * guarding the database.
91
+ *
92
+ * @param resources - the account's resources.
93
+ * @returns group id → the ids of the resources that name it.
94
+ */
95
+ export declare function groupUsers(resources: readonly AccountResource[]): Map<string, string[]>;
96
+ /**
97
+ * Read the policy edges between security groups.
98
+ *
99
+ * ## What makes this an edge
100
+ *
101
+ * A rule on group A whose `remote_group_id` is group B says: traffic from
102
+ * anything carrying B may reach anything carrying A, on this port. That is a
103
+ * statement about reachability between two groups, with a direction and a port
104
+ * — the only relationship in the account that has all three.
105
+ *
106
+ * Two rules that say the same thing (a group's rules are often duplicated by
107
+ * the provider) are collapsed: a reader comparing the picture to the console
108
+ * should not have to work out which arrow is which duplicate.
109
+ *
110
+ * @param resources - the account's resources.
111
+ * @returns the policy edges, sorted for a stable picture.
112
+ */
113
+ export declare function policies(resources: readonly AccountResource[]): PolicyEdge[];
114
+ /**
115
+ * One rule worth showing on a security group's box.
116
+ *
117
+ * ## Why a rule is summarised rather than listed
118
+ *
119
+ * A group's rule list is mostly repetition the cloud adds for every group
120
+ * alike: two self-referencing ingress rules (members may talk to each other)
121
+ * and two egress rules admitting everything. Measured on a live account, 13
122
+ * groups carry 65 rules, and only a handful say anything a reader did not
123
+ * already know. Listing them all makes the picture three times taller for
124
+ * information that is the same in every group.
125
+ *
126
+ * So only a rule that ADMITS SOMETHING SPECIFIC survives: a port range, a
127
+ * source group, or a narrowed address range. What is dropped is reported as a
128
+ * count, not silently — a reader who wants the full list gets it, and a reader
129
+ * scanning the picture gets the rules that distinguish one group from another.
130
+ */
131
+ export interface RuleSummary {
132
+ /** `ingress` or `egress`. */
133
+ readonly direction: string;
134
+ /** The protocol, or `any`. */
135
+ readonly protocol: string;
136
+ /** The port range, or `all` for every port. */
137
+ readonly ports: string;
138
+ /** What it admits from: a group name, a CIDR, or `self`. */
139
+ readonly source: string;
140
+ }
141
+ /**
142
+ * Whether a rule says anything a reader would not assume.
143
+ *
144
+ * Three shapes are assumed and therefore dropped:
145
+ *
146
+ * - a rule admitting the group's own members (`remote_group_id` = itself),
147
+ * which is the cloud's default for any group;
148
+ * - an egress rule admitting everything, which nearly every group has;
149
+ * - an exact duplicate of a rule already kept.
150
+ *
151
+ * @param rule - the provider's rule object.
152
+ * @param groupId - the id of the group the rule belongs to.
153
+ * @param nameOf - resolves a group id to its name.
154
+ * @returns the summary, or `undefined` when the rule says nothing new.
155
+ */
156
+ export declare function summarizeRule(rule: Record<string, unknown>, groupId: string, nameOf: (id: string) => string | undefined): RuleSummary | undefined;
157
+ /**
158
+ * The rules worth showing for one security group, split by direction.
159
+ *
160
+ * @param resources - the account's resources.
161
+ * @returns group id → its ingress and egress summaries, each de-duplicated.
162
+ */
163
+ export declare function ruleSummaries(resources: readonly AccountResource[]): Map<string, {
164
+ readonly ingress: readonly RuleSummary[];
165
+ readonly egress: readonly RuleSummary[];
166
+ }>;
167
+ /**
168
+ * Read all three layers at once.
169
+ *
170
+ * @param resources - the account's resources.
171
+ * @returns the resolved view.
172
+ */
173
+ export declare function accountView(resources: readonly AccountResource[]): AccountView;
174
+ //# sourceMappingURL=account-view.d.ts.map
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Drawing a design with the same layout and renderer as an account.
3
+ *
4
+ * ## Why the two pictures share a renderer
5
+ *
6
+ * A design and an account answer different questions, but they are the same
7
+ * KIND of picture: nested network regions with a few connectors between them.
8
+ * They were drawn by different engines, which meant the same deployment could
9
+ * produce two diagrams whose boxes, spacing and colours did not match — and a
10
+ * reader comparing "what I planned" against "what is running" had to do the
11
+ * mapping in their head.
12
+ *
13
+ * ## What stays different
14
+ *
15
+ * The input vocabulary. A design's nodes are already classified
16
+ * (`vpc`, `subnet`, `security-group`, …) because the classification is what
17
+ * `topology.ts` decides from the configuration; an account's are not, because
18
+ * the inventory names things in its own terms. That difference stops at this
19
+ * module: both become a `LayoutNode` tree, and everything downstream is
20
+ * identical.
21
+ *
22
+ * The one thing the design renderer adds is the distinction the account does
23
+ * not have: a node may be `existing` — a resource the deployment reuses rather
24
+ * than creates — and it is drawn dashed so a reviewer can see at a glance what
25
+ * is already there.
26
+ *
27
+ * @module @huaweidevtools/aishell-dsh-deploy/design-render
28
+ */
29
+ import type { Topology, TopologyEdge, TopologyNode } from './topology.ts';
30
+ import type { Diagram } from './svg-render.ts';
31
+ /**
32
+ * The text a design node's box shows.
33
+ *
34
+ * A rule leads with its EFFECT rather than its name: `ingress 22 ← 0.0.0.0/0`
35
+ * says what it admits, which is what a reviewer checks. Every other kind leads
36
+ * with its cloud name, falling back to the terraform label — the label is what
37
+ * addresses and tool results use, but the cloud name is what the console shows.
38
+ *
39
+ * @param node - the design node.
40
+ * @returns one line of text.
41
+ */
42
+ export declare function designLabel(node: TopologyNode): string;
43
+ /**
44
+ * Build the drawable diagram for a design.
45
+ *
46
+ * @param topology - the derived design.
47
+ * @param edges - the relationships to draw, already filtered to what nesting
48
+ * does not express.
49
+ * @returns the placed boxes, the connectors, and each box's role.
50
+ */
51
+ export declare function buildDesignDiagram(topology: Topology, edges: readonly TopologyEdge[]): Diagram;
52
+ /**
53
+ * Draw the design.
54
+ *
55
+ * @param topology - the derived design.
56
+ * @param edges - the relationships to draw.
57
+ * @returns the SVG and a text record of what it shows.
58
+ */
59
+ export declare function renderDesignDiagram(topology: Topology, edges: readonly TopologyEdge[]): {
60
+ readonly diagram: Diagram;
61
+ readonly svg: string;
62
+ readonly source: string;
63
+ };
64
+ //# sourceMappingURL=design-render.d.ts.map
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Turning the account into the diagram's node tree.
3
+ *
4
+ * ## The three layers, and how each becomes a shape
5
+ *
6
+ * `account-view.ts` reads three kinds of fact. Each has exactly one right
7
+ * drawing, and picking the wrong one is what makes a diagram misleading:
8
+ *
9
+ * - **Placement and attachment** become NESTING. A subnet is inside its VPC;
10
+ * a server is inside its subnet; an EIP is inside the load balancer it
11
+ * answers for. All four are the same claim — "this belongs to that" — and a
12
+ * line between them would say "related", which is weaker and untrue.
13
+ * - **Guarding** becomes TEXT INSIDE the guarded box. A security group is not
14
+ * a peer of the server it protects; it is a property of it. Drawing it as a
15
+ * node with an arrow turns a setting into an entity.
16
+ * - **Policy** becomes an EDGE, in its own band, with the port on it. This is
17
+ * the only relationship in the picture that expresses reachability, and the
18
+ * only one where direction and port mean anything.
19
+ *
20
+ * ## What the picture contains, in order
21
+ *
22
+ * The VPCs and their contents, then a band of the account-level services that
23
+ * belong to no network, then the policy band. Everything the account holds is
24
+ * somewhere; nothing is dropped for being uninteresting, because "uninteresting"
25
+ * would be a rule and a rule needs a source that does not exist here.
26
+ *
27
+ * @module @huaweidevtools/aishell-dsh-deploy/diagram
28
+ */
29
+ import type { Diagram } from './svg-render.ts';
30
+ import type { AccountResource } from './account-view.ts';
31
+ /**
32
+ * Build the drawable diagram for an account.
33
+ *
34
+ * @param resources - everything the inventory reported.
35
+ * @returns the placed boxes, the policy edges, and each box's role.
36
+ */
37
+ export declare function buildDiagram(resources: readonly AccountResource[]): Diagram;
38
+ /**
39
+ * Draw the account as a diagram.
40
+ *
41
+ * @param resources - everything the inventory reported.
42
+ * @returns the SVG and a text record of what it shows.
43
+ */
44
+ export declare function renderAccountDiagram(resources: readonly AccountResource[]): {
45
+ readonly diagram: Diagram;
46
+ readonly svg: string;
47
+ readonly source: string;
48
+ };
49
+ //# sourceMappingURL=diagram.d.ts.map
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Laying out an architecture diagram: boxes inside boxes.
3
+ *
4
+ * ## What this computes, and why it is not delegated
5
+ *
6
+ * A network diagram is a set of nested regions — a region holds VPCs, a VPC
7
+ * holds subnets, a subnet holds resources — and the nesting IS the picture. A
8
+ * general graph layout engine treats nesting as one expression among many: D2's
9
+ * ELK and dagre backends both lay sibling containers out in a row regardless of
10
+ * what is inside them, measured at 4–6:1 on a real account, which is a strip no
11
+ * preview can show.
12
+ *
13
+ * The layout here follows from the structure instead of searching for it:
14
+ *
15
+ * 1. **Size, bottom up.** A leaf is its label plus padding. A container is
16
+ * the packing of its children plus padding and a title band. Nothing is
17
+ * positioned until every box knows its own size.
18
+ * 2. **Place, top down.** A container gives each child a slot inside itself,
19
+ * and the child does the same for its own children. A child is inside its
20
+ * parent by construction, not by a rule that has to be checked afterwards.
21
+ * 3. **Pack siblings toward square.** Given a list of child boxes, the number
22
+ * of columns is the one whose packed block is least elongated. A row of
23
+ * four wide boxes is a strip; two rows of two is a block.
24
+ *
25
+ * Every step is arithmetic on the box tree. There is no iteration, no
26
+ * force-directed relaxation, and no randomness, so two runs of the same account
27
+ * produce the same picture — which is what makes a diagram comparable.
28
+ *
29
+ * ## What it does not do
30
+ *
31
+ * It does not route edges. An edge's endpoints are box borders; drawing the
32
+ * connector between them is the renderer's work, and it is kept apart from
33
+ * placement so a change to one does not silently move the other.
34
+ *
35
+ * @module @huaweidevtools/aishell-dsh-deploy/layout
36
+ */
37
+ /** One node of the tree to lay out. */
38
+ export interface LayoutNode {
39
+ /** Stable identity, used to key edges against the placed boxes. */
40
+ readonly id: string;
41
+ /** The text drawn on the box. Its length is what decides the box's width. */
42
+ readonly label: string;
43
+ /**
44
+ * Whether this box marks something that already existed.
45
+ *
46
+ * A design reuses resources it does not create, and a reviewer checks that
47
+ * distinction first — "am I about to duplicate what we have". It travels with
48
+ * the node rather than being looked up later, because only the caller knows
49
+ * what its own ids mean.
50
+ */
51
+ readonly existing?: boolean;
52
+ /**
53
+ * The service that reported this resource, for its tint.
54
+ *
55
+ * A stable identity: every `ecs` resource shares it however it is named. The
56
+ * layout does not read it — only the renderer does — but it has to travel on
57
+ * the node, because a placed box has no other link back to what it came from.
58
+ */
59
+ readonly provider?: string;
60
+ /**
61
+ * Lines drawn under the label, left-aligned inside the box.
62
+ *
63
+ * A security group's rules belong to the group's own box, and they are detail
64
+ * rather than identity: the name leads, these follow in a smaller face. Left
65
+ * alignment is what makes them scannable — a column of rules read down the
66
+ * left edge, the way a list is read.
67
+ */
68
+ readonly detail?: readonly string[];
69
+ /**
70
+ * A count appended to the label as `[n]`.
71
+ *
72
+ * For a security group it is how many resources use it, which is what
73
+ * separates a live group from a leftover. It rides on the label rather than
74
+ * occupying a band of its own: the name is the identity and the count is a
75
+ * property of it, so `sg-postgresql [1]` reads as one thing.
76
+ */
77
+ readonly figure?: string;
78
+ /** What this box contains. */
79
+ readonly children: readonly LayoutNode[];
80
+ }
81
+ /** A node with its final position. */
82
+ export interface PlacedBox {
83
+ readonly id: string;
84
+ readonly label: string;
85
+ /** The top-left corner, in canvas coordinates. */
86
+ readonly x: number;
87
+ readonly y: number;
88
+ readonly width: number;
89
+ readonly height: number;
90
+ /** The nesting depth; 0 for the outermost box. */
91
+ readonly depth: number;
92
+ /** Whether this box marks something that already existed. */
93
+ readonly existing: boolean;
94
+ /** The service that reported it, for the renderer's tint. */
95
+ readonly provider: string;
96
+ /** Lines under the label, left-aligned inside this box. */
97
+ readonly detail: readonly string[];
98
+ /** A count shown centred under the detail lines. */
99
+ readonly figure: string | undefined;
100
+ readonly children: readonly PlacedBox[];
101
+ }
102
+ /**
103
+ * The text a box carries, with its count in brackets.
104
+ *
105
+ * `sg-postgresql [1]` rather than a separate figure: the count qualifies the
106
+ * name, and putting it there keeps the box one line of identity instead of two
107
+ * blocks a reader has to associate.
108
+ *
109
+ * @param label - the box's own label.
110
+ * @param figure - the count, when there is one.
111
+ * @returns the label with the count appended.
112
+ */
113
+ export declare function labelWithFigure(label: string, figure: string | undefined): string;
114
+ /** A laid-out diagram: every box, flattened, plus the canvas extent. */
115
+ export interface Layout {
116
+ /** Every box, parents before their children. */
117
+ readonly boxes: readonly PlacedBox[];
118
+ /** Only the outermost boxes, whose union is the canvas. */
119
+ readonly roots: readonly PlacedBox[];
120
+ /** The space the drawing needs, before any outer margin. */
121
+ readonly width: number;
122
+ readonly height: number;
123
+ }
124
+ /**
125
+ * Lay out a tree of nested boxes.
126
+ *
127
+ * ## How the roots are arranged
128
+ *
129
+ * The roots are the same layer of the picture — a VPC, a band of shared
130
+ * services — so they are packed beside each other rather than stacked. Which
131
+ * The roots go in ONE row, however narrow the result. They are the top of the
132
+ * picture — regions, usually — and a reader compares them left to right: which
133
+ * region holds the VPC, which holds only a default group. Wrapping them onto
134
+ * several rows puts two regions above two others with nothing saying they are
135
+ * peers, and the eye reads that as a hierarchy that does not exist.
136
+ *
137
+ * Everything below a root is packed by the square rule, because there the
138
+ * alternatives really are equivalent and the aspect decides.
139
+ *
140
+ * @param roots - the outermost boxes.
141
+ * @param margin - space left around the whole drawing.
142
+ * @returns the placed boxes and the canvas extent.
143
+ */
144
+ export declare function layoutTree(roots: readonly LayoutNode[], margin?: number): Layout;
145
+ //# sourceMappingURL=layout.d.ts.map
@@ -0,0 +1,146 @@
1
+ /**
2
+ * Drawing a laid-out diagram as SVG.
3
+ *
4
+ * ## Why this does not go through D2
5
+ *
6
+ * D2 renders a graph: it takes the nodes and the edges and decides where each
7
+ * goes. That is the wrong division of labour for a picture whose structure is
8
+ * already known — the nesting IS the layout — because the engine lays sibling
9
+ * containers out in a row whatever they contain, and no amount of input
10
+ * adjustment changes that (measured at 4–6:1 on a real account).
11
+ *
12
+ * Here the placement is already decided by `layout.ts`, and this module does the
13
+ * one thing left: turn rectangles and connectors into markup. That also makes
14
+ * the theme cheap — two class blocks and CSS `prefers-color-scheme`, rather than
15
+ * a WASM build.
16
+ *
17
+ * ## What it draws
18
+ *
19
+ * - A container's box first, then its label in the title band, then its
20
+ * children. Painting in that order is what puts the frame behind the
21
+ * contents without any clip path.
22
+ * - Edges last, so a connector is never hidden under a box it passes near.
23
+ * Endpoints sit on the box border, computed from the centre-to-centre
24
+ * direction, so a line leaves one box and arrives at another rather than
25
+ * crossing them.
26
+ *
27
+ * @module @huaweidevtools/aishell-dsh-deploy/svg-render
28
+ */
29
+ import type { PlacedBox } from './layout.ts';
30
+ /** How a box is drawn, by the role it plays in the picture. */
31
+ export type BoxRole =
32
+ /** A region, VPC, or subnet: something that holds other things. */
33
+ 'container'
34
+ /** A resource that sits at the bottom of the tree. */
35
+ | 'resource';
36
+ /**
37
+ * Convert HSL to a `#rrggbb` string.
38
+ *
39
+ * The conversion is done here rather than left to the renderer, because several
40
+ * SVG rasterisers do not parse the space-separated CSS Color 4 syntax and fall
41
+ * back to black without reporting anything.
42
+ *
43
+ * @param hue - 0–359.
44
+ * @param saturation - 0–100.
45
+ * @param lightness - 0–100.
46
+ * @returns the colour as hex.
47
+ */
48
+ export declare function hslToHex(hue: number, saturation: number, lightness: number): string;
49
+ /**
50
+ * The hue a service's boxes are tinted with.
51
+ *
52
+ * Keyed by the provider the inventory reports, which is a stable identity: every
53
+ * `ecs` resource is the same service whatever it is called. A hash rather than a
54
+ * table, for the reason the connector colours use one — a table would need a
55
+ * line per service and would be wrong the first time an unfamiliar one appeared.
56
+ *
57
+ * @param provider - the service that reported the resource.
58
+ * @returns a hue in degrees, 0–359.
59
+ */
60
+ export declare function serviceHue(provider: string): number;
61
+ /** One connector between two placed boxes. */
62
+ export interface BoxEdge {
63
+ readonly from: string;
64
+ readonly to: string;
65
+ /** The words on the line, already translated from a property name. */
66
+ readonly label: string;
67
+ /**
68
+ * What the connector asserts.
69
+ *
70
+ * `traffic` is a flow — packets travel this way, and the label says on what
71
+ * port. `policy` is a rule — one group admits another, and nothing moves
72
+ * along it. They are drawn differently because a reader acts on them
73
+ * differently: one is where a request goes, the other is why it is allowed.
74
+ */
75
+ readonly kind: 'traffic' | 'policy';
76
+ }
77
+ /** Everything the renderer needs. */
78
+ export interface Diagram {
79
+ readonly width: number;
80
+ readonly height: number;
81
+ readonly boxes: readonly PlacedBox[];
82
+ readonly edges: readonly BoxEdge[];
83
+ /** The role of each box, by id. A box with no entry is drawn as a resource. */
84
+ readonly roles: ReadonlyMap<string, BoxRole>;
85
+ }
86
+ /**
87
+ * Escape text for XML content and attributes.
88
+ *
89
+ * @param text - the string to escape.
90
+ * @returns the same text with the five XML metacharacters replaced.
91
+ */
92
+ export declare function escapeXml(text: string): string;
93
+ /**
94
+ * Where a connector meets a box's border, on the side facing the other box.
95
+ *
96
+ * The connector is drawn as an orthogonal path, so it leaves through a
97
+ * horizontal edge when the boxes are stacked and through a vertical edge when
98
+ * they are side by side. Picking the side from the relative position is what
99
+ * keeps the first and last segment perpendicular to the border it touches —
100
+ * a line meeting a box at an angle reads as passing behind it.
101
+ *
102
+ * @param box - the box whose border point is wanted.
103
+ * @param towardX - the other box's centre, x.
104
+ * @param towardY - the other box's centre, y.
105
+ * @returns the point on the box's border.
106
+ */
107
+ export declare function borderPoint(box: PlacedBox, towardX: number, towardY: number): {
108
+ readonly x: number;
109
+ readonly y: number;
110
+ };
111
+ /**
112
+ * The points an orthogonal connector turns at.
113
+ *
114
+ * ## Why orthogonal and not straight
115
+ *
116
+ * A straight line between two boxes passes over whatever lies between them —
117
+ * and in a packed box tree, that is the sibling boxes. Measured on a real
118
+ * account: every one of twenty-seven connectors crossed a box that was not one
119
+ * of its endpoints. An orthogonal path with one bend in the gap between rows
120
+ * stays in the empty corridor the layout already leaves there.
121
+ *
122
+ * The path leaves along the axis its border point faces, turns once in the
123
+ * corridor, and arrives along the same axis. Two segments per bend, so the
124
+ * route is always three or four points and never doubles back.
125
+ *
126
+ * @param from - the source box.
127
+ * @param to - the target box.
128
+ * @returns the polyline's points, source first.
129
+ */
130
+ export declare function routePoints(from: PlacedBox, to: PlacedBox): readonly {
131
+ readonly x: number;
132
+ readonly y: number;
133
+ }[];
134
+ /**
135
+ * Render the diagram.
136
+ *
137
+ * The SVG declares `width` and `height` from the layout, not only a `viewBox`.
138
+ * Without them a browser treats the file as a replaced element with no size and
139
+ * lays it out at the CSS default of 300×150, scaling everything into that box —
140
+ * which draws a readable diagram at about one pixel.
141
+ *
142
+ * @param diagram - the placed boxes and connectors.
143
+ * @returns the SVG document, with no XML declaration so it embeds in HTML.
144
+ */
145
+ export declare function renderDiagram(diagram: Diagram): string;
146
+ //# sourceMappingURL=svg-render.d.ts.map
@@ -0,0 +1,105 @@
1
+ /**
2
+ * How traffic reaches the account, read from what the inventory reports.
3
+ *
4
+ * ## What a path is, and why these three kinds
5
+ *
6
+ * A path is a chain of resources where each one hands traffic to the next. The
7
+ * inventory reports three such handoffs, and they are the only ones it reports:
8
+ *
9
+ * - **Public entry** — an EIP names the instance it is attached to
10
+ * (`associateInstanceId`). That is the point where traffic from outside the
11
+ * account meets something inside it.
12
+ * - **Load balancer front end** — a listener names its balancer
13
+ * (`loadbalancers[].id`) and carries the protocol and port it answers on.
14
+ * That is where a request picks its port.
15
+ * - **Balancer back end** — a Kubernetes-managed listener carries the cluster
16
+ * it fronts in its `description`, as JSON. That is the hop from "a port is
17
+ * open" to "these pods are behind it".
18
+ *
19
+ * A chain is assembled by matching a resource's id against the ids other
20
+ * resources name — the same rule the rest of the picture uses. Nothing here is
21
+ * keyed by a service name, so a service that reports the same handoff the same
22
+ * way joins a path without a line of code.
23
+ *
24
+ * ## What it deliberately does not claim
25
+ *
26
+ * It does not infer a hop the data does not state. A server with no recorded
27
+ * address is not assumed to sit behind a balancer, and a balancer's pool is not
28
+ * followed to its members: the inventory lists the pool's id but not its
29
+ * members, so the members are a separate query away. A picture that guessed
30
+ * those would show a flow nobody verified.
31
+ *
32
+ * @module @huaweidevtools/aishell-dsh-deploy/traffic
33
+ */
34
+ import type { AccountResource } from './account-view.ts';
35
+ /** One hop of a path. */
36
+ export interface Hop {
37
+ /** What kind of thing this hop is, for the renderer's wording. */
38
+ readonly kind: 'internet' | 'eip' | 'balancer' | 'listener' | 'target';
39
+ /** The resource id, or `undefined` for the internet itself. */
40
+ readonly id: string | undefined;
41
+ /** The address or port that makes this hop concrete, when there is one. */
42
+ readonly detail: string | undefined;
43
+ }
44
+ /** A chain from outside the account to something inside it. */
45
+ export interface TrafficPath {
46
+ readonly hops: readonly Hop[];
47
+ }
48
+ /**
49
+ * The cluster a listener fronts, when the listener says so.
50
+ *
51
+ * A listener created by the Kubernetes integration records its owner as JSON in
52
+ * `description` — `{"cluster_id": "…", "service_id": "…"}`. That is the only
53
+ * place the hop from the load balancer to the cluster is written down.
54
+ *
55
+ * @param resource - a listener.
56
+ * @returns the cluster id, or `undefined` when the listener is not owned by one.
57
+ */
58
+ export declare function clusterBehind(resource: AccountResource): string | undefined;
59
+ /**
60
+ * Every path the inventory states.
61
+ *
62
+ * @param resources - the account's resources.
63
+ * @returns the paths, each starting at the internet.
64
+ */
65
+ export declare function trafficPaths(resources: readonly AccountResource[]): TrafficPath[];
66
+ /**
67
+ * Continue a chain past its last box, through the policy that admits it.
68
+ *
69
+ * ## The gap this closes, and the limit of closing it
70
+ *
71
+ * A Kubernetes listener records the cluster it fronts, and nothing further: the
72
+ * inventory does not say which pods talk to which database. What it DOES say is
73
+ * that one group admits another on a port, and which resources each group
74
+ * guards — so a cluster guarded by group A, where A's peer group B admits the
75
+ * database, is a flow the account actually states.
76
+ *
77
+ * That is a hop through a rule rather than through a resource, and it is the
78
+ * only continuation the data supports. It is added only when exactly one group
79
+ * admits exactly one guarded target: with several candidates the chain would be
80
+ * a guess, and a guess drawn as a flow is the defect this module exists to
81
+ * avoid.
82
+ *
83
+ * @param resources - the account's resources.
84
+ * @param view - the resolved layers.
85
+ * @returns extra hops, keyed by the resource a chain currently ends at.
86
+ */
87
+ export declare function policyContinuations(resources: readonly AccountResource[], view: {
88
+ readonly guardsOf: ReadonlyMap<string, readonly string[]>;
89
+ readonly policies: readonly {
90
+ readonly from: string;
91
+ readonly to: string;
92
+ readonly direction: string;
93
+ readonly protocol: string;
94
+ readonly ports: string | undefined;
95
+ }[];
96
+ }): Map<string, Hop>;
97
+ /**
98
+ * The name of what a path ends at, for a caption.
99
+ *
100
+ * @param path - the path.
101
+ * @param resources - the account's resources.
102
+ * @returns the last hop's name, or an empty string when it names nothing.
103
+ */
104
+ export declare function pathTarget(path: TrafficPath, resources: readonly AccountResource[]): string;
105
+ //# sourceMappingURL=traffic.d.ts.map