New remote

Purpose: Create resources for a service call.

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

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 Gliimly 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 Gliimly 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 Gliimly 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 Gliimly 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.gliim" source file:

 %% /manage-keys
    do-once
    new-array 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-array h key (key) value data status st
        @Added [<<p-out key>>]
    else-if op equal "delete" // Delete data and obtain the value deleted
        read-array h key (key) value val \
            delete \
            status st
        if-true st equal GG_ERR_EXIST
            @Not found [<<p-out key>>]
        else-if
            // If found, then delete key and value
            @Deleted [<<p-out val>>]
            delete-string val
        end-if
    else-if op equal "query" // Query hash based on key value
        read-array h key (key) value val status st
        if-true st equal GG_ERR_EXIST
            @Not found, queried [<<p-out key>>]
        else-if
            @Value [<<p-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.gliim" and copy to it this code:

 begin-handler /srv
  // 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
  p-out rdata1
  @
  p-out rdata2
  @
  p-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

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]