Skip to content

Commit b4fc60d

Browse files
vexx32joeyaiello
vexx32
authored and
joeyaiello
committed
Test-Connection Changes (#172)
* Create RFCNNNN-Test-Connection.md * Update RFCNNNN-Test-Connection.md * Update RFCNNNN-Test-Connection.md Update RFC per Steve's comments * Update RFCNNNN-Test-Connection.md Update MtuSize property type & give default value * 📝 Rename RoundTripTime -> Latency This name conveys the same thing without being excessively long and causing difficulty effectively formatting the output. * Apply suggestions from code review Update parameter sets * Update RFCNNNN-Test-Connection.md Update RFC & examples * Prepare for acceptance of RFC0037 (Test-Connection)
1 parent 35e0d7c commit b4fc60d

File tree

1 file changed

+206
-0
lines changed

1 file changed

+206
-0
lines changed

‎2-Draft-Accepted/RFC0037-Test-Connection.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
RFC: XXXX
3+
Author: Joel Sallow
4+
Status: Draft
5+
Version: 1.0
6+
Area: Cmdlets
7+
Comments Due: 6/10/19
8+
Plan to Implement: Yes
9+
---
10+
11+
# Proposed Changes to `Test-Connection` Cmdlet
12+
13+
## Syntax
14+
15+
```
16+
# All Sets
17+
Test-Connection [-TargetName] <string[]> [-IPv4] [-IPv6] [-ResolveDestination] [-TimeoutSeconds <int>] [-Quiet] [<CommonParameters>]
18+
19+
# Set 1
20+
[-Ping] [-Count <int>] [-Delay <int>] [-Source <string>] [-MaxHops <int>] [-BufferSize <int>] [-DontFragment]
21+
22+
# Set 2
23+
[-Ping] [-Continues] [-Delay <int>] [-Source <string>] [-MaxHops <int>] [-BufferSize <int>] [-DontFragment]
24+
25+
# Set 3
26+
-Traceroute [-Source <string>] [-MaxHops <int>]
27+
28+
# Set 4
29+
-MTUSizeDetect
30+
31+
# Set 5
32+
-TCPPort <int> [-Source <string>]
33+
```
34+
35+
## Changes
36+
37+
1. All current host/information output is output only to the `-Verbose` stream.
38+
2. No progress bar per committee decision in [PowerShell#6768](https://github.com/PowerShell/PowerShell/issues/6768).
39+
3. All output occurs as soon as data is available, individual records per ping reply / trace hop.
40+
4. All presented data should be readily available as properties to the user.
41+
42+
## Output Type Proposed Members
43+
44+
### PingStatus
45+
46+
```csharp
47+
class PingStatus
48+
{
49+
string Source { get; }
50+
string Destination { get; }
51+
IPAddress Address { get; }
52+
int Latency { get; }
53+
IPStatus Status { get; }
54+
int BufferSize { get; }
55+
56+
// These properties are not displayed by default
57+
PingReply Reply { get; }
58+
PingOptions Options { get; }
59+
}
60+
```
61+
62+
#### PingMtuStatus
63+
64+
```csharp
65+
class PingMtuStatus : PingStatus
66+
{
67+
public int MtuSize { get; }
68+
}
69+
```
70+
71+
### TraceStatus
72+
73+
```csharp
74+
class TraceStatus
75+
{
76+
private PingStatus _status;
77+
78+
int Hop { get; }
79+
string Hostname { get; }
80+
IPAddress HopAddress { get; }
81+
int Latency { get; }
82+
IPStatus Status { get; }
83+
string Source { get; }
84+
string Target { get; }
85+
IPAddress TargetAddress { get; }
86+
PingReply Reply { get; }
87+
PingOptions Options { get; }
88+
}
89+
```
90+
91+
## Mockups
92+
93+
### `Test-Connection www.google.com`
94+
95+
- Information from the `Replies` property of the output object should be included in the main output object, and primary output mode should be _multiple_ objects, each representing a single ping attempt/reply object.
96+
- Buffer _data_ is generally irrelevant, as it cannot be specified, and only a `BufferSize` property should be exposed.
97+
- `Replies.Options` property should be hidden from default formatting.
98+
- Results output as a table, grouped by `Destination` IP / name (in the case that multiple destinations are specified).
99+
100+
**Resulting output:**
101+
```code
102+
Destination: 8.8.8.8
103+
Source Address Latency BufferSize Status
104+
(ms) (B)
105+
------ ------- ------- ---------- ------
106+
WS-JOEL 8.8.8.8 29 32 Success
107+
WS-JOEL 8.8.8.8 22 32 Success
108+
WS-JOEL 8.8.8.8 26 32 Success
109+
WS-JOEL 8.8.8.8 35 32 Success
110+
```
111+
112+
### `Test-Connection www.google.com -TraceRoute`
113+
114+
- Each ping response from a hop should be output as a separate object, each containing the `PingReply` object as a property accessible but hidden from formatting.
115+
- **Note:** .NET Core's `PingReply` objects will always report bad data for `RoundtripTime`, `Status`, and `Options` properties when running a `-TraceRoute` as their status is reported (as it should be) as `TtlExpired` and the rest of the data is essentially discarded. For this reason, these properties are manually populated for `TraceStatus` and the `PingStatus` used in traceroutes.
116+
- A separate `StopWatch` can be used to obtain reasonably accurate `Latency` values.
117+
- The original `PingOptions` and `BufferSize` information can be manually inserted when the `PingStatus` object is created, giving the user the same data as would normally be returned on the `PingReply`
118+
- The `Status` property will be overridden in a traceroute if the status is `TtlExpired`, as that behaviour is completely expected.
119+
- Output as a table, grouped by `Target`.
120+
121+
**Resulting output:**
122+
```code
123+
Target: 8.8.8.8
124+
Hop Hostname Latency Status Source TargetAddress
125+
(ms)
126+
--- -------- ------- ------ ------ -------------
127+
1 192.168.22.254 1 Success WS-JOEL 8.8.8.8
128+
1 192.168.22.254 1 Success WS-JOEL 8.8.8.8
129+
1 192.168.22.254 1 Success WS-JOEL 8.8.8.8
130+
2 75.144.219.238 2 Success WS-JOEL 8.8.8.8
131+
2 75.144.219.238 7 Success WS-JOEL 8.8.8.8
132+
2 75.144.219.238 6 Success WS-JOEL 8.8.8.8
133+
3 96.120.97.17 18 Success WS-JOEL 8.8.8.8
134+
3 96.120.97.17 11 Success WS-JOEL 8.8.8.8
135+
3 96.120.97.17 12 Success WS-JOEL 8.8.8.8
136+
4 96.110.136.85 16 Success WS-JOEL 8.8.8.8
137+
4 96.110.136.85 17 Success WS-JOEL 8.8.8.8
138+
4 96.110.136.85 27 Success WS-JOEL 8.8.8.8
139+
5 68.85.127.121 27 Success WS-JOEL 8.8.8.8
140+
5 68.85.127.121 28 Success WS-JOEL 8.8.8.8
141+
5 68.85.127.121 25 Success WS-JOEL 8.8.8.8
142+
6 68.86.165.161 37 Success WS-JOEL 8.8.8.8
143+
6 68.86.165.161 26 Success WS-JOEL 8.8.8.8
144+
6 68.86.165.161 30 Success WS-JOEL 8.8.8.8
145+
7 68.86.90.205 25 Success WS-JOEL 8.8.8.8
146+
7 68.86.90.205 24 Success WS-JOEL 8.8.8.8
147+
7 68.86.90.205 36 Success WS-JOEL 8.8.8.8
148+
8 68.86.82.70 26 Success WS-JOEL 8.8.8.8
149+
8 68.86.82.70 26 Success WS-JOEL 8.8.8.8
150+
8 68.86.82.70 27 Success WS-JOEL 8.8.8.8
151+
9 23.30.207.242 28 Success WS-JOEL 8.8.8.8
152+
9 23.30.207.242 32 Success WS-JOEL 8.8.8.8
153+
9 23.30.207.242 28 Success WS-JOEL 8.8.8.8
154+
10 108.170.253.17 26 Success WS-JOEL 8.8.8.8
155+
10 108.170.253.17 26 Success WS-JOEL 8.8.8.8
156+
10 108.170.253.17 29 Success WS-JOEL 8.8.8.8
157+
11 216.239.59.125 25 Success WS-JOEL 8.8.8.8
158+
11 216.239.59.125 39 Success WS-JOEL 8.8.8.8
159+
11 216.239.59.125 25 Success WS-JOEL 8.8.8.8
160+
12 8.8.8.8 23 Success WS-JOEL 8.8.8.8
161+
12 8.8.8.8 29 Success WS-JOEL 8.8.8.8
162+
12 8.8.8.8 27 Success WS-JOEL 8.8.8.8
163+
```
164+
165+
166+
## Alternate Proposals & Considerations
167+
168+
### Grouping `TraceStatus` output
169+
The behaviour of `Test-Connection -TraceRoute` prior to this RFC is to output trace data only after all 3 connection attempts have been made.
170+
This behaviour could be retained, and the `TraceStatus` class contain all three `PingStatus` reply objects, with the formatting for `Latency` and `Status` properties showing multiple entries each.
171+
172+
#### `Test-Connection www.google.com -TraceRoute`
173+
174+
- Each hop should be output as a separate object, each containing the `PingReply` objects as a property accessible but hidden from formatting.
175+
- Main `TraceRouteResult` object should contain either ETS or class properties that calculate summary data from their four PingReplies.
176+
- Output as a table, grouped by `Destination`
177+
178+
**Resulting output mockup:**
179+
```code
180+
Destination: www.google.com
181+
Hop Latency (ms) DestinationAddress HopAddress BufferSize
182+
--- ------------ ------------------ ---------- ----------
183+
1 {0, 0, 0} 172.217.2.132 192.168.22.254
184+
2 {0, 0, 0} 172.217.2.132 75.144.219.238
185+
3 {0, 0, 0} 172.217.2.132 96.120.37.17
186+
4 {0, 0, 0} 172.217.2.132 96.110.136.65
187+
5 {0, 0, 0} 172.217.2.132 69.139.180.170
188+
6 {0, 0, 0} 172.217.2.132 68.85.127.121
189+
7 {0, 0, 0} 172.217.2.132 68.86.165.161
190+
8 {0, 0, 0} 172.217.2.132 68.86.90.205
191+
9 {0, 0, 0} 172.217.2.132 68.86.82.154
192+
10 {0, 0, 0} 172.217.2.132 66.208.233.242
193+
11 {0, 0, 0} 172.217.2.132 0.0.0.0
194+
12 {0, 0, 0} 172.217.2.132 216.239.59.124
195+
13 {0, 0, 0} 172.217.2.132 216.239.59.61
196+
14 {32, 28, 20} 172.217.2.132 172.217.2.132
197+
```
198+
199+
However, by outputting one `TraceStatus` object per ping reply, the user is able to follow the trace more closely, and the output is not halted whenever there is a connection timeout.
200+
Additionally, the user can always choose to group the output later simply by doing `Group-Object -Property [Hop|HopAddress|HopName]` if they wish.
201+
202+
### Use the same type of object for `-MtuSizeDetect` switch
203+
204+
This is _plausible_ but requires a change in the table formatter to permit conditional display of properties.
205+
Currently, this has only been shown to be feasible potentially with list-type formatting.
206+
As such, it makes more sense at the present time to have `-MtuSizeDetect` output an object that inherits from the main `PingStatus` object with the added property for `MtuSize`.

0 commit comments

Comments
 (0)