GOLF(2gg)

💅 GOLF(2gg) — the new-remote page, bestie edition 🎀

okay so this is from the Development section of the GOLF(2gg) manual, and it's literally all about new-remote. sit down, grab a boba, we're doing this. ✨

---

🌸 NAME 🌸

new-remote — it's giving (distributed-computing) 💫

---

🎯 PURPOSE 🎯

Create resources for a service call. that's it, that's the whole job. no cap. 🫶

---

📜 SYNTAX 📜

    new-remote <service> \
        ( local <app name> ) | ( location <location> ) \
        url-path <service URL> |
            ( \
            app-path <app path> \
            request-path <request path> \
            [ url-params <url params> ] \
            ) \
        [ request-body content <content> \
            [ content-length <content length> ] \
            [ content-type <content type> ] ] \
        [ method <request method> ] \
        [ environment <name>=<value> [ , ... ] ] \
        [ timeout <timeout> ]

look at all those backslashes, she's serving line-continuation realness 🔥

---

📖 DESCRIPTION 📖

so new-remote will create resources needed for a service call (peep call-remote for that part, iykyk); these resources are contained in variable <service>. ✨

---

🏠 LOCAL OR LOCATION 🏠

if the local clause is used, then service is a Golf application running on the same computer, and the name of this application is string <app name>. same-room vibes, no long distance. 🫶

if local is not used, then you MUST use the location clause. <location> (in the location clause) is a string representing either a Unix socket or a TCP socket of a remote service, and it is:

• for a Unix socket, a fully qualified name to a Unix socket file used to communicate with the service (for a Golf server, it's "/var/lib/gg/<app name>/sock/sock", where <app name> is the application name), or
• for a TCP socket, a host name and a port number in the form of "<host name>:<port number>", specifying where the service is listening on (for instance "127.0.0.1:2301" if the service is local and runs on TCP port 2301).

---

🔗 URL-PATH OR ITS COMPONENTS 🔗

if url-path is used, then it's a URL path to a service. simple. slay. 💅

if url-path is not used, then you MUST use the app-path and request-path clauses, with the optional url-params clause. the <app path> string (in the app-path clause) is the application path used to access a URL resource in service <location>, <request path> string (in the request-path clause) is the request path used to access a URL resource in service <location>, while <url params> string (in the url-params clause) is the URL parameters — see request. 🦋

---

🎀 OPTIONAL 🎀

<request method> string (in the method clause) is a request method, such as "GET", "POST", "DELETE", "PUT" etc. the default is "GET". she's chill like that. 😌

Request body (i.e. body content) is specified via the request-body clause. within it, <content> (in the content subclause) is the actual body content string. <content length> (in the content-length subclause) specifies the number of bytes in <content>; by default it will be the string length of <content> (see string-length). the mandatory <content type> (in the content-type subclause) is the body content type (for instance "application/json" or "image/jpg"). mandatory bestie, don't skip her. 👑

<url params> string (in the url-params clause) is the URL parameters — see request.

<environment> (in the environment clause) is the environment passed to a service call, in the form of "name"="value" string list where such environment elements are separated by a comma. this way you can send any environment variables to the request executed remotely. for a Golf server, you can access those variables in a remote request by using the "environment" clause of the get-sys statement. there is no limit on the number of environment variables you can use this way, other than the underlying communication library. infinite env var glitch, kinda iconic. 🌈

<timeout> (in the timeout clause) is the number of seconds after which a service call will timeout; meaning the duration of a service call should not exceed this period of time. for no timeout, specify 0. note that time needed for a DNS resolution of <location> is not counted in <timeout>. maximum value is 86400 seconds. even though it's optional, it is recommended to specify <timeout> in order to avoid a Golf process waiting for a very long time. note that even if your service call times out, the actual request executing on the server may continue until it's done. 😭 that part is a jumpscare, fr fr — timing out does not cancel the server-side request.

---

🧪 EXAMPLES 🧪

in this example, 3 service calls are created ("srv1", "srv2" and "srv3"), and they will each make a service request. 🔥

each service request will add a key ("key1" with data "data_1", "key2" with data "data_2" and "key3" with data "data_3").

all three service calls connect via Unix socket. 🫶

a full URL path of a service request (for "srv1" for example), would be "/app/manage-keys/op=add/key=key_1/data=data_1" (note that "app" is the application name and "manage-keys" is the request handler that provides the service).

copy this to "manage_keys.golf" source file:

    %% /manage-keys public
       do-once
       new-hash h hash-size 1024 process-scope
       end-do-once

       // Get input parameters
       get-param op
       get-param key
       get-param data

       if-true op equal "add" // Add data to hash,
           write-hash h key (key) value data status st
           @Added [<<print-out key>>]
       else-if op equal "delete" // Delete data and obtain the value deleted
           read-hash h key (key) value val \
               delete \
               status st
           if-true st equal GG_ERR_EXIST
               @Not found [<<print-out key>>]
           else-if
               // If found, then delete key and value
               @Deleted [<<print-out val>>]
               delete-string val
           end-if
       else-if op equal "query" // Query hash based on key value
           read-hash h key (key) value val status st
           if-true st equal GG_ERR_EXIST
               @Not found, queried [<<print-out key>>]
           else-if
               @Value [<<print-out val>>]
           end-if
       end-if
    %%

then call-remote will make three service calls to the above request handler in parallel (i.e. as threads executing at the same time). you can examine if everything went okay, how many threads have started, and how many finished with a reply from the service (this means any kind of reply, even if an error). finally, the output from each call is displayed (that's the "data" clause in the read-remote statement at the end). 👑

create file "srv.golf" and copy to it this code:

    begin-handler /srv public
     // Create resources (prepare) for 3 service calls
     // We pass environment variable GG_SILENT_HEADER to these calls
     // so they don't emit HTTP header
     new-remote srv1 local "app" \
         url-path "/app/manage-keys/op=add/key=key1/data=data1" \
         environment "GG_SILENT_HEADER"="yes"
     new-remote srv2 local "app" \
         url-path "/app/manage-keys/op=add/key=key2/data=data2" \
         environment "GG_SILENT_HEADER"="yes"
     new-remote srv3 local "app" \
         url-path "/app/manage-keys/op=add/key=key3/data=data3" \
         environment "GG_SILENT_HEADER"="yes"
     // Make 3 service calls in parallel, each in it own thread
     call-remote srv1, srv2, srv3 status st \
         started start \
         finished-okay fok
     // Check if all calls were completed
     if-true st equal GG_OKAY
         @No errors from call-remote
     end-if
     if-true start equal 3
         @All three service calls started.
     end-if
     if-true fok equal 3
         @All three service calls finished.
     end-if
     read-remote srv1 data rdata1
     read-remote srv2 data rdata2
     read-remote srv3 data rdata3
     print-out rdata1
     @
     print-out rdata2
     @
     print-out rdata3
     @
    end-handler

create the application:

    sudo mgrg -i -u $(whoami) app

make it:

    gg -q

run it:

    mgrg -w 1 app

    gg -r --req="/srv" --exec --silent-header

and the result is (assuming you have started hash example above):

    No errors from call-remote
    All three service calls started.
    All three service calls finished.
    Added [key1]

    Added [key2]

    Added [key3]

ate. no crumbs. 💅✨

---

👀 SEE ALSO 👀

Distributed computing

call-remote new-remote read-remote run-remote See all documentation

---

and that's the whole page bestie!! 🎀 this version was $VERSION and it dropped on $DATE, living under the GOLF(2gg) banner forever. go make some remote calls, you got this 💖🦋🌸