Reggae tutorial: http.stream

Grzegorz Kraszewski

Idea of live software update

Live software update over Internet is becoming popular in mainstream operating systems and its applications. It is comfortable to users, allows for fast distribution of bugfixes and security updates and also (what is important for commercial products) creates an additional channel of advertising. The general idea of live update is simple. An application connects to a remote server, checks for updates, download them if any found, then install new files in proper places. After that application asks user for a restart and optionally restarts itself.

While it sounds easy in the above description, there are some obstacles on the way. MorphOS provides network connections handling on TCP/UDP protocol level (or socket level API-wise). Some higher level protocol must be used to handle update check and files downloading. It may be some custom thing (which has a big disadvantage that it must be implemented on the server side too), or some standard protocol, like FTP or HTTP. While FTP seems to be better suited, looking at its name, HTTP is more versatile as it allows for easy implementation of additional features on server side like download counters, dynamic content generation, sending information to the server and more.

HTTP is not a very complicated protocol, handling it at socket level is some serious work however. On the other hand using an external application like wget gives very little control over downloading process. MorphOS had no embeddable HTTP client, but now it has one, which is Reggae http.stream class. It is a lightweight implementation of HTTP/1.1 protocol. The only limitation is that it supports GET requests only (it may support also POST in the future).

What is http.stream class?

The http.stream class is just a HTTP/1.1 client which may be used either as a data source for Reggae framework, or standalone as a single component. It allows for easy download of any resource reachable with HTTP GET request. It has also some higher-level functions, which make using HTTP protocol easier. Here is a brief list of features:

• Completely encapsulates socket communication level into an easy to use programming interface. Knowledge of bsdsocket.library API is not required at all, some general knowledge about Internet and HTTP would be an advantage however.
• Unlike bsdsocket.library base instances, http.stream objects may be shared between processes.
• The class has builtin parser of HTTP response headers.
• The class has also an easy to use HTTP request header builder, so custom fields may be added to the header.
• HTTP proxies are supported.
• Optional user agent spoofing is possible.
• When connecting, HTTP redirections may be followed automatically.
• Easy protocol debugging via MediaLogger.

Basic download operation

Basic download operation starts from creation of http.stream instance. URL for the requested resource and other connection details are passed to the constructor as attributes. After succesful construction, response data may be pulled from the output port of the object by calling MMM_Pull() method. When application is finished with downloading data, it just disposes the object.

Following operations are performed while the object is constructed:

• Connection. URL is parsed, hostname and port are extracted and used to make a TCP connection to the remote host. A DNS query is performed before, to convert hostname into an IP address.
• Request. HTTP request is built and sent to the remote host.
• Reply header reception. The object receives HTTP header and parses it.

After succesful object construction, the object is ready to pull response data from its output port. Note that object construction is synchronous to the application. In case of problems like slow DNS response, or connection timeout, the application is waiting. For GUI based applications the whole download should be ran in a subprocess. It can be easily done using some Reggae output class instead of calling MMM_Pull() directly (it will be discussed later).