GOLF(2gg)

okay so bestie, welcome to GOLF(2gg) — the Development manual page for request, aka Golf documentation (requests). no cap, this is the whole vibe. ✨

🌸 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. periodt 🫶

🔗 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:

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

Obsessed. 💅

🛒 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. (yes, bytes, bestie 💀)

👑 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.

🌈 SEE ALSO 🌈

• Requests
• request See all documentation

---

and that's the whole page bestie 💖 this was GOLF(2gg), version $VERSION, dated $DATE. mwah 💅✨