==========
Networking
==========
.. Modified: 2019-10-21/02:39-0400 btiffin
.. Copyright 2016 Brian Tiffin
.. This file is part of the Unicon Programming document
.. GPL 3.0+ :ref:`license`
.. image:: images/unicon.png
:align: center
.. only:: html
:ref:`genindex`
:floatright:`<a href="http://unicon.sourceforge.net/">Unicon</a>`
.. index:: networking
.. _networking:
Unicon Networking
=================
Ahh, the network. Unicon fully supports client server computing using
standard words and phrases.
.. note:: *Update: Nov 16 2016*
Unicon has been setup to run on SourceForge. CGI and other browser friendly
demonstrations will be posted. For instance:
`Simple CGI form echo <http://btiffin.users.sourceforge.net/form.html>`_
.. index:: mode; n, mode; na, mode; nl, mode; nu
Network mode
------------
The :ref:`open` emphatic is used to initiate networking subsystems.
Network mode ``n`` is the network client mode of :ref:`open`.
Network mode ``na`` is network *accept* (blocking server) mode of :ref:`open`.
Network mode ``nl`` is network *listen* (non-blocking server) mode of :ref:`open`.
Protocols include:
- TCP Transmission Control Protocol
- UDP User Datagram Protocol (add ``u`` to the :ref:`open` mode; for example
"nua" for a blocking UDP server)
.. index:: mode; m
Message mode
------------
Message mode ``m`` is a special network mode of :ref:`open`. This is the web
as seen from Unicon. Support for http and https. Use ``m-`` for less secure
but functional unauthenticated https, until local certificates are configured.
.. index:: http
.. _http:
HTTP
....
HyperText Transport Protocol. A text based protocol used in much of the modern
web.
Unicon handles HTTP by using :ref:`open` with a mode of ``m`` (or ``ms`` if
only HTTP headers are needed, and no page data).
.. literalinclude:: examples/http.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/http.icn`
Giving:
.. program-output:: unicon -s http.icn -x
:cwd: examples
.. index:: https
.. _https:
HTTPS
.....
Secure (encrypted) HTTP. The text based HTTP protocol wrapped in encrypted
packets. These packets use TLS and/or SSL encryption technology, a certificate
based key pairing. An initial *usually verified* certificate is hosted by the
server and temporary tokens are delivered to the client (browser) for single
pair communications. This avoids clear text messaging, a rather easy thing to
eavesdrop on, and or change in transit.
As of early Unicon 13 alpha releases, HTTPS is not quite ready. The
encryption works, once setup. It is the setup that is not quite ready. It is
not the smooth setup that will eventually be part of Unicon builds. There is
internal certificate management issues that may require end user intervention.
It will be advertised as ready when a basic build of Unicon does not require
any extraordinary effort on behalf of a Unicon programmer. For example, the
sample below required an externally set ``SSL_CERT_DIR`` environment variable
before Jafar fixed the search path settings in SVN revision 4474 of the Unicon
code base.
.. note::
*Leaving the sample in, as it doesn't "hurt", but this override is no
longer required (at least for Ubuntu based Unicon built from source)*.
.. literalinclude:: examples/https-full.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/https-full.icn`
.. command-output:: SSL_CERT_DIR=/usr/lib/ssl/certs unicon https-full.icn -x
:cwd: examples
:shell:
Without the external certificate finder, the program :strike:`does` did not
function properly.
Now, the environment setting is not necessary.
.. command-output:: unicon https-full.icn -x
:cwd: examples
:shell:
Verify
------
Messaging mode (:ref:`open` mode "m") with ``https`` adds a new, optional,
``-`` flag, for skipping certificate verification. The default is to try and
validate a certificate. ``"m"`` is more secure than ``"m-"``, but does
require some external setup for certificate pairing. Otherwise the system will
block access with::
cannot verify peer's certificate
When validation fails, :ref:`open` will fail.
More HTTPS
----------
The Unicon project is on SourceForge. And the Allura system that makes up
most of the forge user interface supports a rich API.
`Apache Allura public API <https://forge-allura.apache.org/docs/getting_started/administration.html#public-api-documentation>`_
To get the download counts for Unicon, using Unicon:
.. literalinclude:: examples/https-json.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/https-json.icn`
That program will pull down a JSON response from SourceForge. The captured
command output asks ``jq`` (JSON query) for the last entry from the
``downloads`` list from the data displayed by Unicon. *Web server response
headers are also displayed from Unicon, directed to standard error to not
interfere with the JSON data passed to the* ``jq`` *command*. *The capture
only includes a limited range of the header lines from the output, hence the
ellipsis*.
.. command-output:: unicon -s https-json.icn -x | jq .downloads[-4:-1]
:cwd: examples
:ellipsis: 4,-14
SMTP
....
Simple Mail Transfer Protocol
.. todo:: add a mail sending sample
POP
...
Post Office Protocol
You've got mail.
.. todo:: add a mail reader sample
.. index:: CGI, PHP
.. _cgi:
CGI
===
There is a Technical Report (UTR4a 2011/02/04) ``Writing CGI and PHP
Scripts in Icon and Unicon`` that details and lists working samples of
``Common Gateway Interface`` programming with Unicon. Methods for
integrating Unicon with ``PHP`` is also explained.
http://unicon.org/utr/utr4.html
A CGI support layer is built along with ``unicon``, so programmers only need to
``link cgi`` to take advantage of CGI features.
There is a small sample now hosted on SourceForge, to show off a very simple
Unicon CGI program. ``simple-cgi.icn`` can be tried using a form posted at:
http://btiffin.users.sourceforge.net/form.html
*form-cgi.html*
.. literalinclude:: examples/simple-form.html
:language: html
:start-after: +-->
.. only:: html
.. rst-class:: rightalign
:download:`examples/simple-form.html`
That form invokes:
*simple-cgi.icn*
.. literalinclude:: examples/simple-cgi.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/simple-cgi.icn`
Unicon was built on a SourceForge hosted CentOS server using a Developer Web
Services shell. Details of how this was set up is documented in a blog entry,
:ref:`2016-11-13-forge`. There will be more examples posted. An index page
will be placed at
http://btiffin.users.sourceforge.net/demos/index.html
.. index:: RFC3875, CGI spec
CGI 1.1
-------
The full CGI 1.1 specification is referenced in RFC3875,
https://tools.ietf.org/html/rfc3875
AJAX
====
The ``simple.cgi`` demo can also be put to work with an `AJAX
<https://en.wikipedia.org/wiki/Ajax_%28programming%29>`_ interface.
.. literalinclude:: examples/simple-ajax.html
:language: html
:start-after: +-->
.. only:: html
.. rst-class:: rightalign
:download:`examples/simple-ajax.html`
That AJAX example invokes the same server side ``simple-cgi.icn`` as the CGI
form. The server side program is not a CGI application in this case, and there
is not the same set of environment variables that a web server will set up for
CGI programs, but the example program accounts for this to produce AJAX ready
output.
.. index:: PHP
PHP
===
PHP (initially PHP/FI, Personal Home Page/Forms Interpreter, now know as PHP:
Hypertext Preprocessor) is a widely used server side scripting language. PHP
was never really meant to be a programming language, but has attained a lead
position as a tool of choice for many web applications.
.. pull-quote::
"I don’t know how to stop it, there was never any intent to write a
programming language […] I have absolutely no idea how to write a
programming language, I just kept adding the next logical step on the
way."
-- Rasmus Lerdorf
Unicon can leverage that unstoppable project. PHP is almost always
available along side any web server install, and is a feature rich
and well supported web development environment.
.. todo:: add Unicon, PHP integration sample
.. only:: html
..
--------
:ref:`genindex` | Previous: :doc:`database` | Next: :doc:`threading`
|