1 /* 2 Copyright 2015 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 // Package wsstream contains utilities for streaming content over WebSockets. 18 // The Conn type allows callers to multiplex multiple read/write channels over 19 // a single websocket. 20 // 21 // "channel.k8s.io" 22 // 23 // The Websocket RemoteCommand subprotocol "channel.k8s.io" prepends each binary message with a 24 // byte indicating the channel number (zero indexed) the message was sent on. Messages in both 25 // directions should prefix their messages with this channel byte. Used for remote execution, 26 // the channel numbers are by convention defined to match the POSIX file-descriptors assigned 27 // to STDIN, STDOUT, and STDERR (0, 1, and 2). No other conversion is performed on the raw 28 // subprotocol - writes are sent as they are received by the server. 29 // 30 // Example client session: 31 // 32 // CONNECT http://server.com with subprotocol "channel.k8s.io" 33 // WRITE []byte{0, 102, 111, 111, 10} # send "foo\n" on channel 0 (STDIN) 34 // READ []byte{1, 10} # receive "\n" on channel 1 (STDOUT) 35 // CLOSE 36 // 37 // "v2.channel.k8s.io" 38 // 39 // The second Websocket subprotocol version "v2.channel.k8s.io" is the same as version 1, 40 // but it is the first "versioned" subprotocol. 41 // 42 // "v3.channel.k8s.io" 43 // 44 // The third version of the Websocket RemoteCommand subprotocol adds another channel 45 // for terminal resizing events. This channel is prepended with the byte '3', and it 46 // transmits two window sizes (encoding TerminalSize struct) with integers in the range 47 // (0,65536]. 48 // 49 // "v4.channel.k8s.io" 50 // 51 // The fourth version of the Websocket RemoteCommand subprotocol adds a channel for 52 // errors. This channel returns structured errors containing process exit codes. The 53 // error is "apierrors.StatusError{}". 54 // 55 // "v5.channel.k8s.io" 56 // 57 // The fifth version of the Websocket RemoteCommand subprotocol adds a CLOSE signal, 58 // which is sent as the first byte of the message. The second byte is the channel 59 // id. This CLOSE signal is handled by the websocket server by closing the stream, 60 // allowing the other streams to complete transmission if necessary, and gracefully 61 // shutdown the connection. 62 // 63 // Example client session: 64 // 65 // CONNECT http://server.com with subprotocol "v5.channel.k8s.io" 66 // WRITE []byte{0, 102, 111, 111, 10} # send "foo\n" on channel 0 (STDIN) 67 // WRITE []byte{255, 0} # send CLOSE signal (STDIN) 68 // CLOSE 69 package wsstream // import "k8s.io/apimachinery/pkg/util/httpstream/wsstream" 70