// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package tunnel defines an interface for creating a network tunnel from client
// to server.
package tunnel

import "v.io/v23/security/access"

type Tunnel interface {
  // The Forward method is used for network forwarding. All the data sent over
  // the byte stream is forwarded to the requested network address and all the
  // data received from that network connection is sent back on the reply
  // stream.
  Forward(network, address string) stream<[]byte, []byte> error {access.Admin}

  // The ReverseForward method is used for network forwarding from the server
  // back to the client. The server process listens on the requested network
  // address, forwarding all connections by calling Forwarder.Forward on the
  // caller.
  ReverseForward(network, address string) error {access.Admin}

  // The Shell method is used to either run shell commands remotely, or to open
  // an interactive shell. The data received over the byte stream is sent to the
  // shell's stdin, and the data received from the shell's stdout and stderr is
  // sent back in the reply stream. It returns the exit status of the shell
  // command as an integer exit code and a human readable string.
  Shell(command string, shellOpts ShellOpts) stream<ClientShellPacket, ServerShellPacket> (exitCode int32, exitMsg string | error) {access.Admin}
}

type Forwarder interface {
  // The Forward method is used for network forwarding. All the data sent over
  // the byte stream is forwarded to a predetermined network address and all the
  // data received from that network connection is sent back on the reply
  // stream.
  Forward() stream<[]byte, []byte> error {access.Admin}
}

type ShellOpts struct {
  UsePty      bool       // Whether to open a pseudo-terminal.
  Environment []string   // Environment variables to pass to the remote shell.
  WinSize     WindowSize // The size of the window.
}

type WindowSize struct {
  Rows, Cols uint16
}

type ClientShellPacket union {
  // Bytes going to the shell's stdin.
  Stdin      []byte
  // Indicates that stdin should be closed. The presence of this field indicates
  // EOF. Its actual value is ignored.
  EndOfFile  Unused
  // A dynamic update of the window size.
  WinSize    WindowSize
}

// TODO(toddw): Replace Unused with the unnamed empty struct{}.
type Unused struct {}

type ServerShellPacket union {
  // Bytes coming from the shell's stdout.
  Stdout []byte
  // Bytes coming from the shell's stderr.
  Stderr []byte
}