GOLF(2gg)

NAME
new-remote - (distributed-computing)

PURPOSE
Create resources for a service call.

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

DESCRIPTION
new-remote will create resources needed for a service call (see call-remote); these resources are contained in variable <service>.

LOCAL OR LOCATION

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

If "local" is not used, then you must use "location" clause. <location> (in "location" clause) is a string representing either a Unix socket or a TCP socket of a remote service, and 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.

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

OPTIONAL

<request method> string (in "method" clause) is a request method, such as "GET", "POST", "DELETE", "PUT" etc. The default is "GET".

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

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

<environment> (in "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 "environment" clause of get-sys statement. There is no limit on the number of environment variables you can use this way, other than the underlying communication library.

<timeout> (in "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.

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 "data" clause in 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]

SEE ALSO
 Distributed computing

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