OLD | NEW |
1 // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 import 'dart:async'; | 5 export 'web_socket/channel.dart'; |
6 | 6 export 'web_socket/deprecated.dart'; |
7 import 'package:crypto/crypto.dart'; | 7 export 'web_socket/exception.dart'; |
8 | |
9 import 'copy/web_socket_impl.dart'; | |
10 | |
11 /// An implementation of the WebSocket protocol that's not specific to "dart:io" | |
12 /// or to any particular HTTP API. | |
13 /// | |
14 /// Because this is HTTP-API-agnostic, it doesn't handle the initial [WebSocket | |
15 /// handshake][]. This needs to be handled manually by the user of the code. | |
16 /// Once that's been done, [new CompatibleWebSocket] can be called with the | |
17 /// underlying socket and it will handle the remainder of the protocol. | |
18 /// | |
19 /// [WebSocket handshake]: https://tools.ietf.org/html/rfc6455#section-4 | |
20 abstract class CompatibleWebSocket implements Stream, StreamSink { | |
21 /// The interval for sending ping signals. | |
22 /// | |
23 /// If a ping message is not answered by a pong message from the peer, the | |
24 /// `WebSocket` is assumed disconnected and the connection is closed with a | |
25 /// [WebSocketStatus.GOING_AWAY] close code. When a ping signal is sent, the | |
26 /// pong message must be received within [pingInterval]. | |
27 /// | |
28 /// There are never two outstanding pings at any given time, and the next ping | |
29 /// timer starts when the pong is received. | |
30 /// | |
31 /// By default, the [pingInterval] is `null`, indicating that ping messages | |
32 /// are disabled. | |
33 Duration pingInterval; | |
34 | |
35 /// The [close code][] set when the WebSocket connection is closed. | |
36 /// | |
37 /// [close code]: https://tools.ietf.org/html/rfc6455#section-7.1.5 | |
38 /// | |
39 /// Before the connection has been closed, this will be `null`. | |
40 int get closeCode; | |
41 | |
42 /// The [close reason][] set when the WebSocket connection is closed. | |
43 /// | |
44 /// [close reason]: https://tools.ietf.org/html/rfc6455#section-7.1.6 | |
45 /// | |
46 /// Before the connection has been closed, this will be `null`. | |
47 String get closeReason; | |
48 | |
49 /// Signs a `Sec-WebSocket-Key` header sent by a WebSocket client as part of | |
50 /// the [initial handshake]. | |
51 /// | |
52 /// The return value should be sent back to the client in a | |
53 /// `Sec-WebSocket-Accept` header. | |
54 /// | |
55 /// [initial handshake]: https://tools.ietf.org/html/rfc6455#section-4.2.2 | |
56 static String signKey(String key) { | |
57 var hash = new SHA1(); | |
58 // We use [codeUnits] here rather than UTF-8-decoding the string because | |
59 // [key] is expected to be base64 encoded, and so will be pure ASCII. | |
60 hash.add((key + webSocketGUID).codeUnits); | |
61 return CryptoUtils.bytesToBase64(hash.close()); | |
62 } | |
63 | |
64 /// Creates a new WebSocket handling messaging across an existing socket. | |
65 /// | |
66 /// Because this is HTTP-API-agnostic, the initial [WebSocket handshake][] | |
67 /// must have already been completed on the socket before this is called. | |
68 /// | |
69 /// If [stream] is also a [StreamSink] (for example, if it's a "dart:io" | |
70 /// `Socket`), it will be used for both sending and receiving data. Otherwise, | |
71 /// it will be used for receiving data and [sink] will be used for sending it. | |
72 /// | |
73 /// [protocol] should be the protocol negotiated by this handshake, if any. | |
74 /// | |
75 /// If this is a WebSocket server, [serverSide] should be `true` (the | |
76 /// default); if it's a client, [serverSide] should be `false`. | |
77 /// | |
78 /// [WebSocket handshake]: https://tools.ietf.org/html/rfc6455#section-4 | |
79 factory CompatibleWebSocket(Stream<List<int>> stream, | |
80 {StreamSink<List<int>> sink, String protocol, bool serverSide: true}) { | |
81 if (sink == null) { | |
82 if (stream is! StreamSink) { | |
83 throw new ArgumentError("If stream isn't also a StreamSink, sink must " | |
84 "be passed explicitly."); | |
85 } | |
86 sink = stream as StreamSink; | |
87 } | |
88 | |
89 return new WebSocketImpl.fromSocket(stream, sink, protocol, serverSide); | |
90 } | |
91 | |
92 /// Closes the web socket connection. | |
93 /// | |
94 /// [closeCode] and [closeReason] are the [close code][] and [reason][] sent | |
95 /// to the remote peer, respectively. If they are omitted, the peer will see | |
96 /// a "no status received" code with no reason. | |
97 /// | |
98 /// [close code]: https://tools.ietf.org/html/rfc6455#section-7.1.5 | |
99 /// [reason]: https://tools.ietf.org/html/rfc6455#section-7.1.6 | |
100 Future close([int closeCode, String closeReason]); | |
101 } | |
102 | |
103 /// An exception thrown by [CompatibleWebSocket]. | |
104 class CompatibleWebSocketException implements Exception { | |
105 final String message; | |
106 | |
107 CompatibleWebSocketException([this.message]); | |
108 | |
109 String toString() => message == null | |
110 ? "CompatibleWebSocketException" : | |
111 "CompatibleWebSocketException: $message"; | |
112 } | |
OLD | NEW |