Provided by: golf_601.4.41-1_amd64 
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
$DATE $VERSION GOLF(2gg)