node_modules/node-pty/deps/winpty/misc/Notes.txt

   1 Test programs
   2 -------------
   3
   4 Cygwin
   5   emacs
   6   vim
   7   mc     (Midnight Commander)
   8   lynx
   9   links
  10   less
  11   more
  12   wget
  13
  14 Capturing the console output
  15 ----------------------------
  16
  17 Initial idea:
  18
  19 In the agent, keep track of the remote terminal state for N lines of
  20 (window+history).  Also keep track of the terminal size.  Regularly poll for
  21 changes to the console screen buffer, then use some number of edits to bring
  22 the remote terminal into sync with the console.
  23
  24 This idea seems to have trouble when a Unix terminal is resized.  When the
  25 server receives a resize notification, it can have a hard time figuring out
  26 what the terminal did.  Race conditions might also be a problem.
  27
  28 The behavior of the terminal can be tricky:
  29
  30  - When the window is expanded by one line, does the terminal add a blank line
  31    to the bottom or move a line from the history into the top?
  32
  33  - When the window is shrunk by one line, does the terminal delete the topmost
  34    or the bottommost line?  Can it delete the line with the cursor?
  35
  36 Some popular behaviors for expanding:
  37  - [all] If there are no history lines, then add a line at the bottom.
  38  - [konsole] Always add a line at the bottom.
  39  - [putty,xterm,rxvt] Pull in a history line from the top.
  40  - [g-t] I can't tell.  It seems to add a blank line, until the program writes
  41    to stdout or until I click the scroll bar, then the output "snaps" back down,
  42    pulling lines out of the history.  I thought I saw different behavior
  43    between Ubuntu 10.10 and 11.10, so maybe GNOME 3 changed something.  Avoid
  44    using "bash" to test this behavior because "bash" apparently always writes
  45    the prompt after terminal resize.
  46
  47 Some popular behaviors for shrinking:
  48  - [konsole,putty,xterm,rxvt] If the line at the bottom is blank, then delete
  49    it.  Otherwise, move the topmost line into history.
  50  - [g-t] If the line at the bottom has not been touched, then delete it.
  51    Otherwise, move the topmost line into history.
  52
  53 (TODO: I need to test my theories about the terminal behavior better still.
  54 It's interesting to see how g-t handles clear differently than every other
  55 terminal.)
  56
  57 There is an ANSI escape sequence (DSR) that sends the current cursor location
  58 to the terminal's input.  One idea I had was to use this code to figure out how
  59 the terminal had handled a resize.  I currently think this idea won't work due
  60 to race conditions.
  61
  62 Newer idea:
  63
  64 Keep track of the last N lines that have been sent to the remote terminal.
  65 Poll for changes to console output.  When the output changes, send just the
  66 changed content to the terminal.  In particular:
  67  - Don't send a cursor position (CUP) code.  Instead, if the line that's 3
  68    steps up from the latest line changes, send a relative cursor up (CUU)
  69    code.  It's OK to send an absolute column number code (CHA).
  70  - At least in general, don't try to send complete screenshots of the current
  71    console window.
  72
  73 The idea is that sending just the changes should have good behavior for streams
  74 of output, even when those streams modify the output (e.g. an archiver, or
  75 maybe a downloader/packager/wget).  I need to think about whether this works
  76 for full-screen programs (e.g. emacs, less, lynx, the above list of programs).
  77
  78 I noticed that console programs don't typically modify the window or buffer
  79 coordinates.  edit.com is an exception.
  80
  81 I tested the pager in native Python (more?), and I verified that ENTER and SPACE
  82 both paid no attention to the location of the console window within the screen
  83 buffer.  This makes sense -- why would they care?  The Cygwin less, on the other
  84 hand, does care.  If I scroll the window up, then Cygwin less will write to a
  85 position within the window.  I didn't really expect this behavior, but it
  86 doesn't seem to be a problem.
  87
  88 Setting up a TestNetServer service
  89 ----------------------------------
  90
  91 First run the deploy.sh script to copy files into deploy.  Make sure
  92 TestNetServer.exe will run in a bare environment (no MinGW or Qt in the path).
  93
  94 Install the Windows Server 2003 Resource Kit.  It will have two programs in it,
  95 instsrv and srvany.
  96
  97 Run:
  98
  99   InstSrv TestNetServer <path-to-srvany>\srvany.exe
 100
 101 This creates a service named "TestNetServer" that uses the Microsoft service
 102 wrapper.  To configure the new service to run TestNetServer, set a registry
 103 value:
 104
 105   [HKLM\SYSTEM\CurrentControlSet\Services\TestNetServer\Parameters]
 106   Application=<full-path>\TestNetServer.exe
 107
 108 Also see http://www.iopus.com/guides/srvany.htm.
 109
 110 To remove the service, run:
 111
 112   InstSrv TestNetServer REMOVE
 113
 114 TODO
 115 ----
 116
 117 Agent: When resizing the console, consider whether to add lines to the top
 118 or bottom.  I remember thinking the current behavior was wrong for some
 119 application, but I forgot which one.
 120
 121 Make the font as small as possible.  The console window dimensions are limited by
 122 the screen size, so making the font small reduces an unnecessary limitation on the
 123 PseudoConsole size.  There's a documented Vista/Win7 API for this
 124 (SetCurrentConsoleFontEx), and apparently WinXP has an undocumented API
 125 (SetConsoleFont):
 126     http://blogs.microsoft.co.il/blogs/pavely/archive/2009/07/23/changing-console-fonts.aspx
 127
 128 Make the agent work with DOS programs like edit and qbasic.
 129  - Detect that the terminal program has resized the window/buffer and enter a
 130    simple just-scrape-and-dont-resize mode.  Track the client window size and
 131    send the intersection of the console and the agent's client.
 132  - I also need to generate keyboard scan codes.
 133  - Solve the NTVDM.EXE console shutdown problem, probably by ignoring NTVDM.EXE
 134    when it appears on the GetConsoleProcessList list.
 135
 136 Rename the agent?  Is the term "proxy" more accurate?
 137
 138 Optimize the polling.  e.g. Use a longer poll interval when the console is idle.
 139 Do a minimal poll that checks whether the sync marker or window has moved.
 140
 141 Increase the console buffer size to ~9000 lines.  Beware making it so big that
 142 reading the sync column exhausts the 32KB conhost<->agent heap.
 143
 144 Reduce the memory overhead of the agent.  The agent's m_bufferData array can
 145 be small (a few hundred lines?) relative to the console buffer size.
 146
 147 Try to handle console background color better.
 148     Unix terminal emulators have a user-configurable foreground and background
 149 color, and for best results, the agent really needs to avoid changing the colors,
 150 especially the background color.  It's undesirable/ugly to SSH into a machine
 151 and see the command prompt change the colors.  It's especially ugly that the
 152 terminal retains its original colors and only drawn cells get the new colors.
 153 (e.g. Resizing the window to the right uses the local terminal colors rather
 154 than the remote colors.)  It's especially ugly in gnome-terminal, which draws
 155 user-configurable black as black, but VT100 black as dark-gray.
 156     If there were a way to query the terminal emulator's colors, then I could
 157 match the console's colors to the terminal and everything would just work.  As
 158 far as I know, that's not possible.
 159     I thought of a kludge that might work.  Instead of translating console white
 160 and black to VT/100 white and black, I would translate them to "reset" and
 161 "invert".  I'd translate other colors normally.  This approach should produce
 162 ideal results for command-line work and tolerable results for full-screen
 163 programs without configuration.  Configuring the agent for black-on-white or
 164 white-on-black would produce ideal results in all situations.
 165     This kludge only really applies to the SSH application.  For a Win32 Konsole
 166 application, it should be easy to get the colors right all the time.
 167
 168 Try using the screen reader API:
 169  - To eliminate polling.
 170  - To detect when a line wraps.  When a line wraps, it'd be nice not to send a
 171    CRLF to the terminal emulator so copy-and-paste works better.
 172  - To detect hard tabs with Cygwin.
 173
 174 Implement VT100/ANSI escape sequence recognition for input.  Decide where this
 175 functionality belongs.  PseudoConsole.dll?  Disambiguating ESC from an escape
 176 sequence might be tricky.  For the SSH server, I was thinking that when a small
 177 SSH payload ended with an ESC character, I could assume the character was really
 178 an ESC keypress, on the assumption that if it were an escape sequence, the
 179 payload would probably contain the whole sequence.  I'm not sure this works,
 180 especially if there's a lot of other traffic multiplexed on the SSH socket.
 181
 182 Support Unicode.
 183  - Some DOS programs draw using line/box characters.  Can these characters be
 184    translated to the Unicode equivalents?
 185
 186 Create automated tests.
 187
 188 Experiment with the Terminator emulator, an emulator that doesn't wrap lines.
 189 How many columns does it report having?  What column does it report the cursor
 190 in as it's writing past the right end of the window?  Will Terminator be a
 191 problem if I implement line wrapping detection in the agent?
 192
 193 BUG: After the unix-adapter/pconsole.exe program exits, the blinking cursor is
 194 replaced with a hidden cursor.
 195
 196 Fix assert() in the agent.  If it fails, the failure message needs to be
 197 reported somewhere.  Pop up a dialog box?  Maybe switch the active desktop,
 198 then show a dialog box?
 199
 200 TODO: There's already a pconsole project on GitHub.  Maybe rename this project
 201 to something else?  winpty?
 202
 203 TODO: Can the DebugServer system be replaced with OutputDebugString?  How
 204 do we decide whose processes' output to collect?
 205
 206 TODO: Three executables:
 207   build/winpty-agent.exe
 208   build/winpty.dll
 209   build/console.exe
 210
 211 BUG: Run the pconsole.exe inside another console.  As I type dir, I see this:
 212       D:\rprichard\pconsole>
 213       D:\rprichard\pconsole>d
 214       D:\rprichard\pconsole>di
 215       D:\rprichard\pconsole>dir
 216     In the output of "dir", every other line is blank.
 217     There was a bug in Terminal::sendLine that was causing this to happen
 218     frequently.  Now that I fixed it, this bug should only manifest on lines
 219     whose last column is not a space (i.e. a full line).