GOLF(2gg)

📦 version 601.4.41, in ubuntu questing

GOLF(2gg) 💖 the call-remote page

okay bestie, this one lives in the GOLF(2gg) manual (that's the Development section, for the record), and it's all about making remote service calls. pull up a chair, grab a boba 🧋, let's go.

✨ NAME ✨

call-remote — (distributed-computing) 🦋

🎯 PURPOSE 🎯

Make a remote service call. that's it. that's the whole vibe. 💅

📜 SYNTAX 📜

call-remote <service> [ ,... ]   \
    [ status <status> ]  \
    [ started <started> ] \
    [ finished-okay <finished okay> ]

🌸 DESCRIPTION 🌸

call-remote makes service call(s), just like it says on the tin — either for a single <service> or for a whole list of <service>s. Unless you only named a single <service>, every call runs in parallel with the others (as multiple threads). call-remote is done when all the <service> calls are done. and heads up: every <service> you use here must have already been created with new-remote. no new-remote, no call. periodt.

A <service> call goes out to a remote service. and what's a "remote service", you ask? it means a process accepting requests that is not the same process executing call-remote. it might be on the same computer, it might be on a whole different computer, or it might literally be a different process started by the very same application you're running. so "remote" is doing a lot of work here, iykyk. 😌

💫 Multiple service calls in parallel

Running multiple <service> calls in parallel? iconic. you do it by giving a list of *<service>*s separated by a comma.

There is no limit on how many *<service>*s you can call at the same time — the only thing holding you back is your underlying Operating System resources, like threads/processes and sockets. so like... the OS is the vibe check here. 🫶

💫 Call status

The <status> number (in the "status" clause) will be:

  • GG_OKAY if all <service> calls each returned GG_OKAY — meaning all have started and all have finished with a valid message from the service.
  • GG_ERR_FAILED if at least one did not (for example if the service could not be contacted, if there was a network error etc.).
  • GG_ERR_MEMORY if out of memory.
  • GG_ERR_TOO_MANY if there is too many calls (more than 1,000,000).
⚠️ no cap: GG_OKAY does not mean the reply is considered a success in any logical sense. it only means the request was made and a reply was received according to the service protocol. that's it. don't read into it bestie 😭

💫 Request(s) status

also important: the actual application status for each <service>, plus any data returned and any application errors, can be obtained via the "exit-status", "data" and "error" clauses of the read-remote statement, respectively. so call-remote tells you the call happened; read-remote tells you what it said. two different girlies, two different jobs. 💅

💫 Request(s) duration

call-remote will wait for all <service> requests to finish. for that reason, it is a good idea to specify the "timeout" clause in new-remote for each <service> used, so you can limit the time you'd be waiting around like 🧍. use read-remote to detect a timeout — in which case the "exit-status" clause would produce GG_CLI_ERR_TIMEOUT.

💫 How many calls started and finished

<started> (in the "started" clause) will be the number of service calls that have started.

<finished okay> (in the "finished-okay" clause) is the number of calls that have finished with a return value of GG_OKAY as described above.

so by using <status>, <started> and <finished okay> together, you may surmise whether the results of call-remote meet your expectations. receipts, basically. 🧾✨

💫 Performance, security

call-remote is faster than call-web because it does not use HTTP protocol; instead it only uses a small and binary protocol, which is extremely fast — especially when using Unix sockets on the same machine (see new-remote). 🏎️💨

🚨 but listen: the binary protocol does not have any inherent security built-in. that is part of the reason why it is fast. so as such, it is very well suited for remote service calls on the same machine, or between networked machines on a secure network. do not be sending this over the open internet, bestie, I am begging 🙈

🌈 EXAMPLES 🌈

This example will connect to local Unix socket file /var/lib/gg/app_name/sock/sock (a Golf application named "app_name"), and make a request named "server" (i.e. it will be processed by source code file server.golf) with URL path of /op=add/key=2 (meaning with input parameters op=add and key=2). Then, the service reply is read and displayed.

// Create single call
new-remote srv location "/var/lib/gg/app_name/sock/sock" \
    method "GET" app-path "/app_name" request-path "/server" \
    url-params "/op=add/key=2"
// Call single service call
call-remote srv finished-okay sfok
// Get results of a remote service call
read-remote srv data rdata
// Display results
@Data from service is <<print-out rdata>>

If you are connecting to a service via TCP (and not with a Unix socket like in the example above), the "location" clause in new-remote might be:

new-remote srv location "192.168.0.28:2400" \
    method "GET" app-path "/app_name" request-path "/server" \
    url-params "/op=add/key=2"

In this case, you are connecting to another service (running on IP "192.168.0.28") on port 2400. See mgrg on how to start a service that listens on a TCP port. You would likely use TCP connectivity only if a service you're connecting to is on a different computer. 🖥️➡️🖥️

See also new-remote.

👀 SEE ALSO 👀

Distributed computing ✨

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

and that's the whole page, bestie, you ate that 💅🌟

this was version $VERSION, dated $DATE, from the GOLF(2gg) manual — mwah, take care of her 🎀🦋💖

📦 where this page comes from