Serve a single connection represented by a DuplexStream.

1. The actual server behaviour is only determined by its configuration. The default configuration rejects all authentication and service requests, so you will need to adapt it to your use-case.
2. The AuthAgent will be used to authenticate to the client. It is usually sufficient to use a KeyPair as agent.
3. This operation does not return unless the other side either gracefully closes the connection or an error occurs (like connection loss). All expected exceptional conditions get caught and are reflected in the return value.
4. If the connection needs to be terminated by the server, this can be achieved by throwing an asynchronous exception to the executing thread. All depdendant threads and resources will be properly freed and a disconnect message will be delivered to the client (if possible). It is a good idea to run serve within an Async which can be canceled on demand.

Example:

runServer :: Socket -> IO ()
runServer sock = do
    keyPair <- newKeyPair
    serve conf keyPair sock
    where
        conf = def { userAuthConfig   = def { onAuthRequest         = handleAuthRequest }
                   , connectionConfig = def { onSessionRequest      = handleSessionRequest
                                            , onDirectTcpIpRequest  = handleDirectTcpIpRequest
                                            }
                   }

handleAuthRequest :: UserName -> ServiceName -> PublicKey -> IO (Maybe UserName)
handleAuthRequest user service pubkey = case user of
  "simon" -> pure (Just user)
  _       -> pure Nothing

handleSessionRequest :: identity -> SessionRequest -> IO (Maybe SessionHandler)
handleSessionRequest _ _ = pure $ Just $ SessionHandler $ env mterm mcmd stdin stdout stderr -> do
    sendAll stdout "Hello, world!\n"
    pure ExitSuccess

handleDirectTcpIpRequest :: identity -> DirectTcpIpRequest -> IO (Maybe DirectTcpIpHandler)
handleDirectTcpIpRequest _ req =
    | port (dstPort req) == 80 = pure $ Just $ DirectTcpIpHandler $ stream -> do
          bs <- receive stream 4096
          sendAll stream "HTTP/1.1 200 OK\n"
          sendAll stream "Content-Type: text/plain\n\n"
          sendAll stream "Hello, world!\n"
          sendAll stream "\n"
          sendAll stream bs
          pure ()
    | otherwise = pure Nothing

The server configuration.

• The type variable identity represents the return type of the user authentication process. It may be chosen freely. The identity object will be supplied to all subsequent service handler functions and can be used as connection state.

Configuration for the user authentication layer.

After a successful key exchange the client will usually request the user-auth service to authenticate against. In this implementation, the user-auth service is the only service available after key exchange and the client must request the connection layer through the authentication layer. Except for transport messages, all other message types will result in a disconnect as long as user authentication is in progress (looking at you, libssh ;-)

Information associated with the session request.

Might be exteded in the future.

The session handler contains the application logic that serves a client's shell or exec request.

• The Command parameter will be present if this is an exec request and absent for shell requests.
• The TermInfo parameter will be present if the client requested a pty.
• The Environment parameter contains the set of all env requests the client issued before the actual shell or exec request.
• stdin, stdout and stderr are streams. The former can only be read from while the latter can only be written to. After the handler has gracefully terminated, the implementation assures that all bytes will be sent before sending an eof and actually closing the channel. has gracefully terminated. The client will then receive an eof and close.
• A SIGILL exit signal will be sent if the handler terminates with an exception. Otherwise the client will receive the returned exit code.

handler :: SessionHandler
handler = SessionHandler $ \env mterm mcmd stdin stdout stderr -> case mcmd of
    Just "echo" -> do
        bs <- receive stdin 1024
        sendAll stdout bs
        pure ExitSuccess
    Nothing ->
        pure (ExitFailure 1)

The Environment is list of key-value pairs.

Environment [ ("LC_ALL", "en_US.UTF-8") ]

The TermInfo describes the client's terminal settings if it requested a pty.

NOTE: This will follow in a future release. You may access the constructor through the Internal module, but should not rely on it yet.

The Command is what the client wants to execute when making an exec request (shell requests don't have a command).

When the client makes a DirectTcpIpRequest it requests a TCP port forwarding.

The DirectTcpIpHandler contains the application logic that handles port forwarding requests.

There is of course no need to actually do a real forwarding - this mechanism might also be used to give access to process internal services like integrated web servers etc.

• When the handler exits gracefully, the implementation assures that all bytes will be sent to the client before terminating the stream with an eof and actually closing the channel.