App server

The Arc distribution includes a simple application server in app.arc. The two main features of the app server are account management and improved forms handling.

Running the server

The server can be started simply with

arc>(asv 8080)

However, it is generally better to start the server in a separate thread, so the Arc REPL can be used. This allows the web server to be modified while it is running.

arc> (thread (asv 8080))

Account management

The app server implements user accounts, so a web user can log into a particular account. Optionally, an account can be an "admin" account with access to the administrative features. A user logs into an account with a login form.
The user can then log out of the account. The app server also provides web-based account creation and password modification.

The user login uses a simple browser cookie to keep track of the login. Note that the user account management is entirely orthogonal to the fnid-based continuations of the Arc web server. Logins are maintained through a cookie; fnids are passed in the URL or a form field. The app server includes several mechanisms to ensure that a fnid callback is executed by the expected user.

The app server defines the following pages:
/whoami: displays the logged-in userid and IP address, or redirects to login.
/login: logs user in or creates new account.
/logout: logs the current user out.
/admin: displays the administrative page, if the user is logged into an admin account.
/mismatch: displays an error "Dead link: users don't match." This page is used when a fnid is accessed by the wrong (or logged-out) user.

The following is an example page with user authentication; it will run at http://localhost:8080/example. First, the handler ensures the user is logged in, and displays the login page otherwise. The page displays a form saying "This is the example page". When submitted, the page will say, "Hello user". The uform form ensures that the user is still logged in when the form is submitted; otherwise, the page will display the dead link error.

The following example illustrates urform. The page http://localhost:8080/urexample will accept a value in a form. When submitted, the continuation function will output a cookie header and redirect to the page "uexample", which will display the cookies.

Improved forms

The second feature provided by the app server is improved form functionality: markdown and typed forms.

Markdown is a simple mechanism for adding some formatting to plain text. Text surrounded by asterisks is converted to italics. URLs are converted to links. Blank lines indicate paragraph breaks. Lines that are indented and separated from previous lines by a blank line are displayed as preformatted code.
The Arc app server provides mechanisms to convert markdown text to HTML, and supports markdown input in forms.

The app server also provides a mechanism to create forms consisting of multiple typed fields in a table. For example, a form can have one string input and one integer input. The types are entirely separate from Arc's datatypes. The following table outlines the supported types:

Type

Form field

Result

string

text input of width formwid*

String

string1

text input of width formwid*

String, empty not allowed

int

text input of width numwid*

Integer (rounded)

num

text input of width numwid*

Number

posint

text input of width numwid*

Integer > 0 (rounded)

doc

textarea input of width bigformwid*

String

text

textarea input of width formwid*

String

mdtext

textarea input of width formwid*

Markdown text

mdtext2

textarea input of width formwid*

Markdown text, no links

toks

text input of width formwid*

List of string tokens

bigtoks

textarea input of width formwid*

List of tokens

sexpr

text input of width formwid*

List of S-expressions.

hexcol

text input

String if the string defines a valid hex color

url

text input of width formwid*

URL (empty string allowed).

users

text input of width formwid*

List of usernames with bad names filtered out

choice

select dropdown menu.

Type from the choice list

yesno

select dropdown with "yes" and "no" choices.

Boolean, true for input "yes"

The choice type is specified as a list: choice, the type of the choices, and the choices themselves, for instance '(choice int 1 2 3). The mdtext and mdtext2 inputs include a help link to formatdoc-url*.

A typed form is generated by vars-form, which is a fairly complex procedure. It takes a list of field specifications, where each field specification is a list
of (type label value view modify question). The type specifier is from the above table. The label is the name assigned to the input field. The initial value of the field is value. If view is nil, the field is skipped. If modify is nil, the field is not modifiable; it is displayed as text rather than an input field. If question is defined, it appears as a caption above the field; otherwise, the label is displayed before the field.

The following example shows a form created by vars-form. When the form is submitted, each name and value is printed, followed by "Done!". The user must log in, if not already logged in.
The example runs at the URL http://localhost:8080/vars-form.

Tests that str is of the appropriate length and contains no bad characters.

>(goodname "abc")
"abc"

>(goodname "ab!")
nil

logout-useruser

Logs out user. The user's entry is removed from logins*, cookie->user*, user->cookie*, and the updated cookie->user* is written to cookfile*.

>(logout-user "foo")
nil

set-pwuser pw

Creates (or updates) account with the name user and password pw. Saves hpasswords* in hpwfile*.

>(set-pw "foo" "bar")

defoplname parm [body]

Version of defop to create handler that will redirect to login page if the user is not logged in.

>(defopl foo req (prn "Welcome!"))

uformuser req after [body ...]

Generates form that ensures it was submitted by user (by using when-umatch). body outputs the form body to stdout. After submission, the continuation code after is executed; req specifies the varible name in after to receive the request.

>(uform user req (prn "Result") (prn "The form") (submit))

urformuser req after [body ...]

Generates form with redirection target with guard that user submitted it. After submission, the continuation expression after is executed and must return the redirect string; req specifies the varible name in after to receive the request.

Test user for use with redirect. If user is the user associated with req, executes body. Otherwise returns "mismatch", to redirect to the mismatch page.

>(when-umatch/r user req (logout-user user) "example")

ulinkuser text [body ...]

Outputs a HTML link with text. When clicked, the link will execute body if the user matches user. Similar to onlink, but with the user guard. Renamed from userlink in arc3.

>(userlink user "click here" (prn "Thanks for clicking"))

admin-pageuser [msg]

Generates the administrator page. This page allows new accounts to be created. The current admin login (user) is displayed at the top of the page, along with msg, if present.

>(admin-page user "Please administer...")

login-pageswitch [msg [afterward]]

Generates a login page. switch is 'register, 'login, or 'both, allowing account creation, account login, or both operations respectively. The top of the page displays msg. After the page completes, the afterward continuation is executed (by default hello-page). afterward is either a function or a (function, redirect-string) pair. The function takes the user name and IP as arguments.

Typed and marked-up forms

vars-formuser fields f done [button [lasts]]

Generates a form for user. fields is a list of (type label value view modify question) lists specifying the form. When submitted, f is executed on each field, with the arguments label newval. Then continuation function done is executed. If there is a modifiable field, a submit button is generated with label specified by button. The lifetime of the associated fnid can be specified with lasts.

md-from-formstr [nolinks]

Converts str to markdown after escaping it. URLs will be converted to links unless nolinks is set. Used to generate markdown from form input.

Prints HTML for an input field of type typ, name id, and value val. typ is one of
bigtoks, date, doc, int, lines, mdtext, mdtext2, num, posint, string, string1, sym, syms, text, time, toks, url, users. The type of field and the processing of val depend on typ.

Generates table rows for a varfield list of fields. If liveurls is true, will make links to URLs.

indented-codes i [newlines [spaces]]

Tests if s is indented code under the markup rules. Returns a pair of the index of the start of the code, and the number of spaces of indentation. Returns nil if not indented code. The first i characters are skipped.

>(indented-code "\n\n abc" 0)
(4 2)

parabreaks i [newlines]

If s starts with a paragraph break (at least one blank line), returns the index of the start of the paragraph. Otherwise returns nil. Skips the first i characters.

>(parabreak "\n\nabc\ndef" 0)
2

urlends i

Finds the logical end of a URL embedded in a string, and returns the index of the first character not in the URL. The first i characters are skipped.