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