Ubuntu Manpage: request - Golf documentation (requests)

NAME

       request - Golf documentation (requests)

DESCRIPTION

Golf applications run by processing requests. A request always takes form of an HTTP request, meaning a
URL, an optional HTTP request body, and any environment variables. This is regardless of whether it's a
service or a command-line program.

REQUEST URL

A "request URL" is a URL that an outside caller (such as a web browser) uses to execute your Golf code.
Aside from the scheme, domain and port, it's made up of:

• application path,

• request path, and

• URL parameters.

Here's a breakdown of URL structure:

For example, in the following URL:

https://your.website.com/my-app/my-request/par1=val1/par2=val2

"/my-app" is application path, "/my-request" is request path and "/par1=val1/par2=val2" are parameters
"par1" and "par2" with values "val1" and "val2". Together, application path and request path are called
URL path.

APPLICATION PATH

The leading part of URL's path is called "application path". By default, application path is the
application name (see mgrg with "-i" option) preceded by forward slash ("/"); if it's "shopping", then
the default application path is:

/shopping

Application name can contain alphanumerical characters and hyphens.

- Customizing application path

You can change the application path by specifying it with "--path" parameter in gg when building; each
application must have its own unique path. Note that whatever it may be, the application name must always
be its last path segment. For example, if your application name is "shopping", then the application path
may be:

/api/v2/shopping

An example of specifying the custom application path:

gg -q --path="/api/v2/shopping"

REQUEST PATH

Request path follows the application path, for instance:

https://some.web.site/shopping/buy-item

In this case the application path is "/shopping" and the request path is "/buy-item". It means that file
"buy-item.golf" handles request "/buy-item" by implementing a begin-handler "/buy-item" in it. As another
example, file "services/manage-home.golf" (meaning "manage-home.golf" file in subdirectory "services")
handles request "/services/manage-home" etc.

The request path must match (fully or partially) the path of the file name that implements it, with
source directory being the root ("/"). Here is an example of implementing a request "/buy-item" in file
"buy-item.golf":

begin-handler /buy-item public
get-param some_param
@Bought item: <<print-out some_param>>
end-handler

As an example of a path hierarchy, such as for example a hierarchy of resources, methods etc, begin-
handler may be:

begin-handler /items/wine-collection/red-wine/buy-item public
...
end-handler

then the URL to call it would be:

https://some.web.site/shopping/items/wine-collection/red-wine/buy-item

and might be implemented in file "items/wine-collection/red-wine/buy-item.golf", meaning under
subdirectory "items", then subdirectory "wine-collection", then subdirectory "red-wine", then file "buy-
item.golf".

- File/path naming conventions

By default, a request handler would be implemented in a source file whose path matches the request path,
either fully or partially.

The simplest example is that "/buy-item" request must be implemented in file "buy-item.golf".

As a more involved example, request handler for "/items/wine-collection/red-wine/buy-item" can be
implemented in file "items.golf" or file "items/wine-collection.golf" or file "items/wine-collection/red-
wine.golf" or file "items/wine-collection/red-wine/buy-item.golf".

Each of these source files can contain any number of matching requests. For instance, file "items.golf"
can contain request handlers for both "/items/wine-collection/red-wine/buy-item" and "/items/beer-
collection/ipa-beer/buy-item"; while file "items/wine-collection.golf" can contain request handlers for
both "items/wine-collection/red-wine" and "items/wine-collection/white-wine".

By the same token, file "items/wine-collection/red-wine/buy-item.golf" can implement both "/items/wine-
collection/red-wine/buy-item" and "/items/wine-collection/red-wine/buy-item/sale" requests, as both
requests match the file path.

Note that if you use "--single-file" option in gg, then each source ".golf" file must contain only a
single request, and its request path must match the file path fully. So in this case, request handler for
"/items/wine-collection/red-wine/buy-item" must be in file "items/wine-collection/red-wine/buy-
item.golf", and no other request can be implemented in it.

URL PARAMETERS

The actual input parameters follow after the request path, and can be specified in a number of ways. A
parameter value is generally URL encoded in any case.

- Path segments

A common way is to specify name and value separated by an equal sign within a single path segment:

https://some.web.site/shopping/buy-item/sku=4811/price=600/

This way, you have a readable representation of parameter names and values, while still maintaining the
hierarchical form which conveys how are the parameters structured.

Here, the required request path is "/buy-item" and there are two input parameters ("sku" and "price")
with values of "4811" and "600" respectively.

- Query string

Parameters can be specified after a question mark in a "name=value" form. For example, the full URL (with
the same parameter values as above) may be:

https://some.web.site/shopping/buy-item?sku=4811&price=600

- Mixed

You can specify a mix of the above ways to write parameters, for instance the above URL can be written
as:

https://some.web.site/shopping/buy-item/sku=4811?price=600

- Parameters

A parameter name can be comprised of alphanumeric characters, hyphens and underscores, and it must start
with an alphabet character. Any hyphens are converted to underscores for the purpose of obtaining
parameter value, see get-param. Do not use double underscore ("__") in parameter names.

Structuring your parameters, i.e. the order in a query path or path segments, and which ones (if any) are
in a query string, is determined by you. Regardless of your choices, the code that handles a request is
the same. In the example used here, you can obtain the parameters in request handler source file "buy-
item.golf":

begin-handler /buy-item public
get-param sku
get-param price

run-query @mydb = "update wine_items set price='%s' where sku='%s'" : price, sku no-loop
@OKAY
end-handler

For a hierarchical URL path, you would write the same:

begin-handler /items/wine-collection/red-wine/buy-item public
get-param sku
get-param price

run-query @mydb = "update wine_items set price='%s' where sku='%s'" : price, sku no-loop
end-handler

MAXIMUM LENGTH

Maximum length of a request URL is 2500 bytes.

HOW GOLF HANDLES REQUESTS

There are generally two kinds of requests, depending on their origin. If a request comes from outside the
process that's serving it, then it's an "external" request (such as from a web browser, a web API client,
from command line execution etc). Conversely, if a request comes from inside the process that's serving
it, it's an "internal" request - meaning one request handler is calling another within one the
process(es) serving an application. Internal requests are made using call-handler statement.

An external request is handled by a first available process:

• For a command-line program, there is only a single process, and it handles a single requests before
it exits.

• For a service application, there can be any number of processes running. A process is chosen to
service a request if it is currently not serving other requests; this way there are no processes
waiting idle unnecessarily. Each process is identical and can serve any request, i.e. it has all
request handlers available to it. Thus, when a process is chosen to serve a request, then this
process will simply execute its begin-handler.

- Processing a request

To handle a request, a process first calls a Golf dispatcher, which is automatically generated. It uses a
request name to call the appropriate request handler, as explained above.

You can implement two hooks into request handling: one that executes before each request (before-handler)
and one that executes afterwards (after-handler).

At the end of the request, all request memory and all file handles allocated by Golf will be freed,
except for process-scoped memory (see memory-handling).

- Performance

Golf uses a hash table to match a request with a handler function, as well to match parameters.
Typically, it takes only a single lookup to find the handler function/parameters, regardless of the
number of possible request names/parameters a process may serve (be it 10 or 10,000 different names).
Golf pre-generates a hash table at compile time, so no run-time cycles are spent on creating it. Also,
the hash table is created as a continuous block of memory in the program's data segment, which loads as a
part of the program (as a single memory copy) and is very fast because accessing the data needs no
pointer translations. As a result, Golf dispatcher is extremely fast.

- Unrecognized requests

If no request has been recognized (i.e. request name does not match any request-handling ".golf" source
file), then

• no request handler will execute,

• before-handler and after-handler will not execute either,

• and a "Request not found" error will be reported via report-error.

NAME

DESCRIPTION

SEE ALSO