Request
Gliimly 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 Gliimly code. Aside from the scheme, domain and port, it's made up of:
Here's a breakdown of URL structure:
<scheme>://<domain>[:<port>]<application path><request path><parameters>

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.gliim" handles request "/buy-item" by implementing a begin-handler "/buy-item" in it. As another example, file "services/manage-home.gliim" (meaning "manage-home.gliim" 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.gliim":
 begin-handler /buy-item public
     get-param some_param
     @Bought item: <<p-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.gliim", meaning under subdirectory "items", then subdirectory "wine-collection", then subdirectory "red-wine", then file "buy-item.gliim".

- 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.gliim".

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

Each of these source files can contain any number of matching requests. For instance, file "items.gliim" 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.gliim" 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.gliim" 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 ".gliim" 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.gliim", 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.gliim":
 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 Gliimly handles requests
An incoming request is handled by a first available process:
- Processing a request
To handle a request, a process first calls a Gliimly 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 Gliimly will be freed, except for process-scoped memory (see memory-handling).

- Performance
Gliimly 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). Gliimly 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, Gliimly dispatcher is extremely fast.

- Unrecognized requests
If no request has been recognized (i.e. request name does not match any request-handling ".gliim" source file), then
See also
Requests
request  
See all
documentation

Copyright (c) 2019-2024 Gliim LLC. All contents on this web site is "AS IS" without warranties or guarantees of any kind.