Alpha Server Help
Name:Alpha Server
Version:3.1
Last update:2020-05-27 14:28:40



Description

This always-on AlphaTcl package sets up a server socket to listen to requests for the execution of Tcl commands. Any command line tool could use this socket in order to send commands to be executed by Alpha's Tcl interpreter. You do not have to do anything for this socket to be established: the Alpha Server package is activated automatically during Alpha's startup.
Currently, the Alpha distribution provides two command line scripts which work as clients of the Alpha Server:

Technical information

For security reasons, the commands sent to the Alpha server are executed by a safe Tcl interpreter. This interpreter is restricted and can only execute the following three commands: corresponding to the type of commands that can come from the alphac and the ralpha scripts.

Extending the Alpha Server

You can tweak the Alpha server to accept other commands if needed to set up more complex inter-application communications. All you have to do is to redefine the list variable alphaServer::authorizedCommands, lappend'ing the needed commands. You can place such a redefinition in your prefs.tcl file after a [alphaServer.tcl] statement (which forces the original definition to come first; your redefinition overrides).
However, you should be aware of the security risk implied by allowing arbitrary commands: someone on another computer may use the server to have Alpha execute malicious Tcl commands. The server is meant to accept connections only from the local host, but the check is a bit heuristic and a hacker might be able to fool this check. Therefore, it is recommended to use an IP firewall to block remote connections to unauthorized ports. For Mac OS X users, this amounts to:
  1. Do not enable remote Apple Events.
  2. Activate the firewall in the Sharing System Preferences panel.

Connecting to the Alpha Server

To request the execution of a Tcl command by Alpha, simply connect to the socket on which the server listens and write the command followed by an END OF TRANSMISSION control code (\04 or ^D).
If your script is written in Tcl, you may use the [socket] command to create the client connection: for an example, have a look at the alphac source code.
If your script is a bash script, you may use the /dev/tcp/ device to send your data. For an example, have a look at the ralpha source code.
If you need to transmit some data (like a string or the contents of a file), you may delimit the data by a START OF TEXT control code (\02 or ^B) and an END OF TEXT control code (\03 or ^C). The Alpha Server will automatically append the data to the AlphaTcl proc as an args argument.
More specifically here is the order in which your script must send its request:

Synchronous command

In order to wait for the editing to finish (wait for the window to be closed) precede the command by the token -wait followed by a space character. Then Alpha Server won't close the connection after receiving the command but will use it to send back the name of the edited file when it is closed. If several windows are open, Alpha Server will wait until the last one is closed and send the filename of this last window through the connection.
If the -wait token is not present in front of the command then the command is executed asynchronously. In that case, the client channel is closed as soon as Alpha has finished reading the incoming data.

Getting the port number

The number of the port on which the server socket listens may be predefined via the Alpha Server Port global preference found in the General Preferences panel. By default, this is set to 51954. If Alpha can't open a socket on this port (because it is already in use by another process), then a port is attributed automatically by the Tcl [socket] command. It is put in the environment variable ALPHASERVERPORT to make it accessible to any sub-process of Alpha.
Other processes may also read this port number of the Alpha Server from a file named: 
/tmp/$USER-AlphaServerPort
where $USER is the login name of the user who has launched Alpha.
An AlphaTcl package may also invoke the alphaServer::port proc to get the port number.
Note also that the alphac and ralpha scripts support a -p option to specify a port number in the command line if necessary.

Known problems

There may be conflicts in case you run several versions of Alpha simultaneously on your machine. Each time a version of Alpha is launched, it opens a socket and stores the port number in the environment variable ALPHASERVERPORT and in the file /tmp/$USER-AlphaServerPort. If another version is launched afterwards, its port number will overwrite the port number written by the previous one.
Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2003-2020, Frédéric Boulanger.
All rights reserved.
The Alpha Server package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL FRÉDÉRIC BOULANGER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.