sunet/doc/latex/intro.tex

\section{Overview}\label{sec:intro}
\subsection{What's in sunet?}

The Scheme Underground Network Package contains a set of libraries for
doing Net hacking from Scheme/scsh. It includes:
   
\begin{description}
\item{An smtp client library.}\\
  Forge mail from the comfort of your own Scheme process.
          
\item{rfc822 header library}\\
  Read email-style headers. Useful in several contexts (smtp, http,
  etc.)
          
\item{Simple structured HTML output library} \\
  Balanced delimiters, etc.
          
\item{The SU Web server}\\
  This is a complete implementation of an HTTP 1.0 server in Scheme.
  The server contains other standalone packages that may separately be
  of use:
  \begin{itemize}
  \item URI and URL parsers and unparsers.
  \item A library to help writing CGI scripts in Scheme.
  \item Server extensions for interfacing to CGI scripts.
  \item Server extensions for uploading Scheme code.
  \end{itemize}            

  The server has three main design goals:
  \begin{description}
  \item{Extensibility}\\
    The server is in fact nothing but extensions, using a mechanism
    called ``path handlers'' to define URL-specific services. It has a
    toolkit of services that can be used as-is, extended or built
    upon. User extensions have exactly the same status as the base
    services.
                
    The extension mechanism allows for easy implementation of new
    services without the overhead of the CGI interface.  Since the
    server is written on top of the Scheme shell, the full set of Unix
    system calls and program tools is available to the implementor.
                
  \item{Mobile code}\\
    The server allows Scheme code to be uploaded for direct execution
    inside the server. The server has complete control over the code,
    and can safely execute it in restricted environments that do not
    provide access to potentially dangerous primitives (such as the
    ``delete file'' procedure.)
                
  \item{Clarity}\\
    I\footnote{That's Olin Shivers (\ex{shivers@ai.mit.edu},
      \ex{http://www.\ob{}ai.\ob{}mit.\ob{}edu/\ob{}people/\ob{}shivers/}).
      For the rest of the documentation, if not mentioned otherwise,
      `I' refers to him.} wrote this server to help myself understand
    the Web. It is voluminously commented, and I hope it will prove to
    be an aid in understanding the low-level details of the Web
    protocols.
                
    The S.U. server has the ability to upload code from Web clients
    and execute that code on behalf of the client in a protected
    environment.
          
    Some simple documentation on the server is available.
  \end{description}
\end{description}

          
\subsection{Obtaining the system}

The network code is available by
ftp\footnote{\ex{ftp://ftp-swiss.ai.mit.edu/pub/scsh/contrib/net/net.tar.gz}}.
To run the server, you need our 0.6 release of
scsh\footnote{http://www.scsh.net}. Beyond actually running the
server, the separate parser libraries and other utilites may be of use
as separate modules.

The sunet package contains following parts:
%
\begin{itemize}
\item Several servers (HTTP, CGI, FTP)
\item Several clients (to FTP, SMTP, POP3, NTP)
\item procedures to handle URIs
\item procedures to handle RFC822 headers
\item analogue of \verb|ls| for scsh
\item {\dots}
\end{itemize}

\subsection{What is in this docu?}
%
Unfortunately not all parts of sunet are documented here. If you miss
something, have a look in the source files -- they are alle well
documented (I hope so!).

Currently the ftp server, the ftp client, the modules containing the
procedures handling URIs and URLs, the module handling RFC~822
headers, the netrc package, the save evaluation environment
\ex{toothless\=eval} and the obsolete library for using strings are
documented.

\subsection{How to use the modules}
%
% I think it is a good idea to tell the people how to use
% scsh / sunet as the docu of scsh does not really do this
% (as long as concerning my experience). Additionally, possible
% programmers should be introduced how to create own modules, 
% including those in sunet.
%FIXME
\FIXME{Does anybody have a good idea how to tell newbies how to use
 the packages? I do not feel capable enough for this.}

For the time being, it may help to look at the following. Scsh is started
in the sunet directory. Then, the description file of the modules is
loaded and the ftp-module is opened (to use a ftp client). After the
things are done, scsh is finished via the \verb|,exit| command.
\begin{code}
atari-2600[72] scsh-0.6
Welcome to scsh 0.6.0 (Chinese Democracy)
Type ,? for help.
> ,config ,load modules.scm
modules.scm
> ,open ftp
Load structure ftp (y/n)? y
[ecm-utilities ecm-utilities.scm]
[netrc netrc.scm]
[ftp ftp.scm]
> ; do something nasty
> ,exit
atari-2600[73]\end{code}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: