Debian Codegraph @

LspCpp/third_party/ixwebsocket/docs/ws.md

raw
1 ## General
2
3 ws is a command line tool that should exercise most of the IXWebSocket code, and provide example code.
4
5 ```
6 ws is a websocket tool
7 Usage: ws [OPTIONS] SUBCOMMAND
8
9 Options:
10 -h,--help Print this help message and exit
11
12 Subcommands:
13 send Send a file
14 receive Receive a file
15 transfer Broadcasting server
16 connect Connect to a remote server
17 chat Group chat
18 echo_server Echo server
19 broadcast_server Broadcasting server
20 ping Ping pong
21 curl HTTP Client
22 httpd HTTP server
23 ```
24
25 ## curl
26
27 The curl subcommand try to be compatible with the curl syntax, to fetch http pages.
28
29 Making a HEAD request with the -I parameter.
30
31 ```
32 $ ws curl -I https://www.google.com/
33
34 Accept-Ranges: none
35 Alt-Svc: quic=":443"; ma=2592000; v="46,43",h3-Q048=":443"; ma=2592000,h3-Q046=":443"; ma=2592000,h3-Q043=":443"; ma=2592000
36 Cache-Control: private, max-age=0
37 Content-Type: text/html; charset=ISO-8859-1
38 Date: Tue, 08 Oct 2019 21:36:57 GMT
39 Expires: -1
40 P3P: CP="This is not a P3P policy! See g.co/p3phelp for more info."
41 Server: gws
42 Set-Cookie: NID=188=ASwfz8GrXQrHCLqAz-AndLOMLcz0rC9yecnf3h0yXZxRL3rTufTU_GDDwERp7qQL7LZ_EB8gCRyPXGERyOSAgaqgnrkoTmvWrwFemRLMaOZ896GrHobi5fV7VLklnSG2w48Gj8xMlwxfP7Z-bX-xR9UZxep1tHM6UmFQdD_GkBE; expires=Wed, 08-Apr-2020 21:36:57 GMT; path=/; domain=.google.com; HttpOnly
43 Transfer-Encoding: chunked
44 Vary: Accept-Encoding
45 X-Frame-Options: SAMEORIGIN
46 X-XSS-Protection: 0
47 Upload size: 143
48 Download size: 0
49 Status: 200
50 ```
51
52 Making a POST request with the -F parameter.
53
54 ```
55 $ ws curl -F foo=bar https://httpbin.org/post
56 foo: bar
57 Downloaded 438 bytes out of 438
58 Access-Control-Allow-Credentials: true
59 Access-Control-Allow-Origin: *
60 Connection: keep-alive
61 Content-Encoding:
62 Content-Length: 438
63 Content-Type: application/json
64 Date: Tue, 08 Oct 2019 21:47:54 GMT
65 Referrer-Policy: no-referrer-when-downgrade
66 Server: nginx
67 X-Content-Type-Options: nosniff
68 X-Frame-Options: DENY
69 X-XSS-Protection: 1; mode=block
70 Upload size: 219
71 Download size: 438
72 Status: 200
73 payload: {
74 "args": {},
75 "data": "",
76 "files": {},
77 "form": {
78 "foo": "bar"
79 },
80 "headers": {
81 "Accept": "*/*",
82 "Content-Length": "7",
83 "Content-Type": "application/x-www-form-urlencoded",
84 "Host": "httpbin.org",
85 "User-Agent": "ixwebsocket/7.0.0 macos ssl/OpenSSL OpenSSL 1.0.2q 20 Nov 2018 zlib 1.2.11"
86 },
87 "json": null,
88 "origin": "155.94.127.118, 155.94.127.118",
89 "url": "https://httpbin.org/post"
90 }
91 ```
92
93 Passing in a custom header with -H.
94
95 ```
96 $ ws curl -F foo=bar -H 'my_custom_header: baz' https://httpbin.org/post
97 my_custom_header: baz
98 foo: bar
99 Downloaded 470 bytes out of 470
100 Access-Control-Allow-Credentials: true
101 Access-Control-Allow-Origin: *
102 Connection: keep-alive
103 Content-Encoding:
104 Content-Length: 470
105 Content-Type: application/json
106 Date: Tue, 08 Oct 2019 21:50:25 GMT
107 Referrer-Policy: no-referrer-when-downgrade
108 Server: nginx
109 X-Content-Type-Options: nosniff
110 X-Frame-Options: DENY
111 X-XSS-Protection: 1; mode=block
112 Upload size: 243
113 Download size: 470
114 Status: 200
115 payload: {
116 "args": {},
117 "data": "",
118 "files": {},
119 "form": {
120 "foo": "bar"
121 },
122 "headers": {
123 "Accept": "*/*",
124 "Content-Length": "7",
125 "Content-Type": "application/x-www-form-urlencoded",
126 "Host": "httpbin.org",
127 "My-Custom-Header": "baz",
128 "User-Agent": "ixwebsocket/7.0.0 macos ssl/OpenSSL OpenSSL 1.0.2q 20 Nov 2018 zlib 1.2.11"
129 },
130 "json": null,
131 "origin": "155.94.127.118, 155.94.127.118",
132 "url": "https://httpbin.org/post"
133 }
134 ```
135
136 ## connect
137
138 The connect command connects to a websocket endpoint, and starts an interactive prompt. Line editing, such as using the direction keys to fetch the last thing you tried to type) is provided. That command is pretty useful to try to send random data to an endpoint and verify that the service handles it with grace (such as sending invalid json).
139
140 ```
141 ws connect wss://echo.websocket.org
142 Type Ctrl-D to exit prompt...
143 Connecting to url: wss://echo.websocket.org
144 > ws_connect: connected
145 Uri: /
146 Handshake Headers:
147 Connection: Upgrade
148 Date: Tue, 08 Oct 2019 21:38:44 GMT
149 Sec-WebSocket-Accept: 2j6LBScZveqrMx1W/GJkCWvZo3M=
150 sec-websocket-extensions:
151 Server: Kaazing Gateway
152 Upgrade: websocket
153 Received ping
154 Received ping
155 Received ping
156 Hello world !
157 > Received 13 bytes
158 ws_connect: received message: Hello world !
159 > Hello world !
160 > Received 13 bytes
161 ws_connect: received message: Hello world !
162 ```
163
164 ```
165 ws connect 'ws://jeanserge.com/v2?appkey=_pubsub'
166 Type Ctrl-D to exit prompt...
167 Connecting to url: ws://jeanserge.com/v2?appkey=_pubsub
168 > ws_connect: connected
169 Uri: /v2?appkey=_pubsub
170 Handshake Headers:
171 Connection: Upgrade
172 Date: Tue, 08 Oct 2019 21:45:28 GMT
173 Sec-WebSocket-Accept: LYHmjh9Gsu/Yw7aumQqyPObOEV4=
174 Sec-WebSocket-Extensions: permessage-deflate; server_max_window_bits=15; client_max_window_bits=15
175 Server: Python/3.7 websockets/8.0.2
176 Upgrade: websocket
177 bababababababab
178 > ws_connect: connection closed: code 1000 reason
179
180 ws_connect: connected
181 Uri: /v2?appkey=_pubsub
182 Handshake Headers:
183 Connection: Upgrade
184 Date: Tue, 08 Oct 2019 21:45:44 GMT
185 Sec-WebSocket-Accept: I1rqxdLgTU+opPi5/zKPBTuXdLw=
186 Sec-WebSocket-Extensions: permessage-deflate; server_max_window_bits=15; client_max_window_bits=15
187 Server: Python/3.7 websockets/8.0.2
188 Upgrade: websocket
189 ```
190
191 It is possible to pass custom HTTP header when doing the connection handshake,
192 the remote server might process them to implement a simple authorization
193 scheme.
194
195 ```
196 src$ ws connect -H Authorization:supersecret ws://localhost:8008
197 Type Ctrl-D to exit prompt...
198 [2020-12-17 22:35:08.732] [info] Authorization: supersecret
199 Connecting to url: ws://localhost:8008
200 > [2020-12-17 22:35:08.736] [info] ws_connect: connected
201 [2020-12-17 22:35:08.736] [info] Uri: /
202 [2020-12-17 22:35:08.736] [info] Headers:
203 [2020-12-17 22:35:08.736] [info] Connection: Upgrade
204 [2020-12-17 22:35:08.736] [info] Sec-WebSocket-Accept: 2yaTFcdwn8KL6IzSMj2u6Le7KTg=
205 [2020-12-17 22:35:08.736] [info] Sec-WebSocket-Extensions: permessage-deflate; server_max_window_bits=15; client_max_window_bits=15
206 [2020-12-17 22:35:08.736] [info] Server: ixwebsocket/11.0.4 macos ssl/SecureTransport zlib 1.2.11
207 [2020-12-17 22:35:08.736] [info] Upgrade: websocket
208 [2020-12-17 22:35:08.736] [info] Received 25 bytes
209 ws_connect: received message: Authorization suceeded!
210 [2020-12-17 22:35:08.736] [info] Received pong ixwebsocket::heartbeat::30s::0
211 hello
212 > [2020-12-17 22:35:25.157] [info] Received 7 bytes
213 ws_connect: received message: hello
214 ```
215
216 If the wrong header is passed in, the server would close the connection with a custom close code (>4000, and <4999).
217
218 ```
219 [2020-12-17 22:39:37.044] [info] Upgrade: websocket
220 ws_connect: connection closed: code 4001 reason Permission denied
221 ```
222
223 ## echo server
224
225 The ws echo server will respond what the client just sent him. If we use the
226 simple --http_authorization_header we can enforce that client need to pass a
227 special value in the Authorization header to connect.
228
229 ```
230 $ ws echo_server --http_authorization_header supersecret
231 [2020-12-17 22:35:06.192] [info] Listening on 127.0.0.1:8008
232 [2020-12-17 22:35:08.735] [info] New connection
233 [2020-12-17 22:35:08.735] [info] remote ip: 127.0.0.1
234 [2020-12-17 22:35:08.735] [info] id: 0
235 [2020-12-17 22:35:08.735] [info] Uri: /
236 [2020-12-17 22:35:08.735] [info] Headers:
237 [2020-12-17 22:35:08.735] [info] Authorization: supersecret
238 [2020-12-17 22:35:08.735] [info] Connection: Upgrade
239 [2020-12-17 22:35:08.735] [info] Host: localhost:8008
240 [2020-12-17 22:35:08.735] [info] Sec-WebSocket-Extensions: permessage-deflate; server_max_window_bits=15; client_max_window_bits=15
241 [2020-12-17 22:35:08.735] [info] Sec-WebSocket-Key: eFF2Gf25dC7eC15Ab1135G==
242 [2020-12-17 22:35:08.735] [info] Sec-WebSocket-Version: 13
243 [2020-12-17 22:35:08.735] [info] Upgrade: websocket
244 [2020-12-17 22:35:08.735] [info] User-Agent: ixwebsocket/11.0.4 macos ssl/SecureTransport zlib 1.2.11
245 [2020-12-17 22:35:25.157] [info] Received 7 bytes
246 ```
247
248 ## Websocket proxy
249
250 ```
251 ws proxy_server --remote_host ws://127.0.0.1:9000 -v
252 Listening on 127.0.0.1:8008
253 ```
254
255 If you connect to ws://127.0.0.1:8008, the proxy will connect to ws://127.0.0.1:9000 and pass all traffic to this server.
256
257 You can also use a more complex setup if you want to redirect to different websocket servers based on the hostname your client is trying to connect to. If you have multiple CNAME aliases that point to the same server.
258
259 A JSON config file is used to express that mapping ; here connecting to echo.jeanserge.com will proxy the client to ws://localhost:8008 on the local machine (which actually runs ws echo_server), while connecting to bavarde.jeanserge.com will proxy the client to ws://localhost:5678 where a cobra python server is running. As a side note you will need a wildcard SSL certificate if you want to have SSL enabled on that machine.
260
261 ```
262 echo.jeanserge.com=ws://localhost:8008
263 bavarde.jeanserge.com=ws://localhost:5678
264 ```
265 The --config_path option is required to instruct ws proxy_server to read that file.
266
267 ```
268 ws proxy_server --config_path proxyConfig.json --port 8765
269 ```
270
271 ## File transfer
272
273 ```
274 # Start transfer server, which is just a broadcast server at this point
275 ws transfer # running on port 8080.
276
277 # Start receiver first
278 ws receive ws://localhost:8080
279
280 # Then send a file. File will be received and written to disk by the receiver process
281 ws send ws://localhost:8080 /file/to/path
282 ```
283
284 ## HTTP Client
285
286 ```
287 $ ws curl --help
288 HTTP Client
289 Usage: ws curl [OPTIONS] url
290
291 Positionals:
292 url TEXT REQUIRED Connection url
293
294 Options:
295 -h,--help Print this help message and exit
296 -d TEXT Form data
297 -F TEXT Form data
298 -H TEXT Header
299 --output TEXT Output file
300 -I Send a HEAD request
301 -L Follow redirects
302 --max-redirects INT Max Redirects
303 -v Verbose
304 -O Save output to disk
305 --compress Enable gzip compression
306 --connect-timeout INT Connection timeout
307 --transfer-timeout INT Transfer timeout
308 ```