racket-ssh-2012/ssh-channel.rkt

#lang racket/base

(require racket/set)
(require racket/match)

(require "ssh-numbers.rkt")
(require "ssh-message-types.rkt")
(require "ssh-exceptions.rkt")

(require "os2-support.rkt")

(provide (struct-out ssh-channel)
	 (struct-out channel-stream-credit)
	 (struct-out channel-stream-data)
	 (struct-out channel-stream-extended-data)
	 (struct-out channel-stream-eof)
	 (struct-out channel-stream-notify)
	 (struct-out channel-stream-request)
	 (struct-out channel-stream-ok)
	 (struct-out channel-stream-fail))

;; A CloseState is one of
;; - 'neither, indicating that neither side has signalled closure
;; - 'local, only the local end has signalled closure
;; - 'remote, only the remote end has signalled closure
;; - 'both, both ends have signalled closure.
;; Represents local knowledge of the state of a shared shutdown state
;; machine.
;;
;;                'neither
;;                /       \
;;              \/         \/
;;           'local      'remote
;;               \         /
;;                \/     \/
;;                  'both

;; A ChannelState is a (ssh-channel ...) TODO
;; Named ssh-channel to avoid conflicts with Racket's built-in
;; synchronous channels.
(struct ssh-channel (my-ref ;; Uint32
		     your-ref ;; Maybe<Uint32>
		     type ;; String
		     continuations ;; TransactionManager (see ordered-rpc.rkt)
		     outbound-window ;; Maybe<Natural>
		     outbound-packet-size ;; Maybe<Natural>
		     inbound-window ;; Natural
		     eof-state ;; CloseState covering EOF signals
		     close-state ;; CloseState covering CLOSE signals
		     )
	#:transparent)

;; ChannelMessage = (channel-message ChannelStreamName ChannelMessageBody)
;; Relates a message to a particular stream within a channel within a
;; connection.
(struct channel-message (stream-name body) #:prefab)

;; ChannelStreamName = (channel-stream-name Boolean Boolean Any)
;; Names a stream within a channel within a connection. Unique within
;; a particular connection. If (inbound?) is true, this is the stream
;; of packets from the remote peer to the local peer; if false, the
;; reverse. If (locally-originated?) is true, then the local peer is
;; the one that opened this channel, and the local peer is reponsible
;; for choosing the (identifier) and ensuring that it is unique with
;; respect to other locally-originated streams within this connection;
;; if false, the remote peer opened the channel, and the (identifier)
;; is chosen managed by the connection-control code.
(struct channel-stream-name (inbound? locally-originated? identifier) #:prefab)

;; A ChannelMessageBody is one of
;; -- (channel-stream-credit NonNegativeInteger) **
;;    Informs the publisher that it may transmit another (count)
;;    bytes.
;; -- (channel-stream-data Bytes)
;;    Data intended for the subscriber.
;; -- (channel-stream-extended-data Uint32 Bytes)
;;    Extended data intended for the subscriber. The type code is one
;;    of those defined in ssh-numbers.rkt; for example,
;;    SSH_EXTENDED_DATA_STDERR.
;; -- (channel-stream-eof)
;;    Signals the end of the data stream. Notice that channel closure
;;    is signalled with presence changes.
;; -- (channel-stream-notify Bytes Bytes)
;;    One-way notification of SSH_MSG_CHANNEL_REQUEST.
;; -- (channel-stream-request Bytes Bytes)
;;    RPC SSH_MSG_CHANNEL_REQUEST request.
;; -- (channel-stream-ok) **
;;    RPC SSH_MSG_CHANNEL_REQUEST reply.
;; -- (channel-stream-fail) **
;;    RPC SSH_MSG_CHANNEL_REQUEST error.
;;
;; Messages marked ** travel "upstream", from subscriber to publisher.
(struct channel-stream-credit (count) #:prefab)
(struct channel-stream-data (bytes) #:prefab)
(struct channel-stream-extended-data (type bytes) #:prefab)
(struct channel-stream-eof () #:prefab)
(struct channel-stream-notify (type bytes) #:prefab)
(struct channel-stream-request (type bytes) #:prefab)
(struct channel-stream-ok () #:prefab)
(struct channel-stream-fail () #:prefab)