Phoenix Linden: /* Strings */

2007-08-03T18:24:56Z

Strings

@@ Line 22: / Line 22: @@
 | 'agent-id':foo, 'item-id':bar
 | agent/foo/inventory/item/bar
 |}

Phoenix Linden: /* c++ */

2007-08-03T18:24:23Z

c++

← Older revision		Revision as of 11:24, 3 August 2007
Line 120:		Line 120:
	* string substitution		* string substitution
	* url substitution		* url substitution

			== perl ==
			In <code>Indra::WebServices</code>, you can call <code>buildService($service_name)</code> to make a client to that service. The current implementation supports:
			* string substitution
			* query string substitution
			* recursive substitution

Phoenix Linden: New page: Like any substitution syntax, using untrusted formatted strings or untrusted sources of data can lead to exploits. Be careful when designing the usage so that no tainted input winds up in ...

2007-07-12T19:51:05Z

New page: Like any substitution syntax, using untrusted formatted strings or untrusted sources of data can lead to exploits. Be careful when designing the usage so that no tainted input winds up in ...

New page

Like any substitution syntax, using untrusted formatted strings or untrusted sources of data can lead to exploits. Be careful when designing the usage so that no tainted input winds up in the context.

= Syntax =
The syntax is based on placing curly braces inside an URL to indicate that the curly brace and everything inside should be replaced with a substitution. Each type of substitution will have it's own rules but every time you see { and } then all contents inside those braces are to be replaced.

== Strings ==
String substitution uses an open curly brace '{' followed by a dollar symbol '$' followed by the name of the substitution and a closing curly brace '}'. The name is used as a key into a map whose value will be replaced into the original format string. The key must only contain alphanumeric characters and '+', '-', '_', and spaces.

Values which appear in the map but not referenced in the format string are ignored.

{| border="1"
|+ String Substitution Examples
! Format !! Map Contents !! Result
|-
| {$bucket}.agent.lindenlab.com
| 'bucket':'a'
| a.agent.lindenlab.com
|-
| agent/{$agent-id}/inventory/item/{$item-id}
| 'agent-id':foo, 'item-id':bar
| agent/foo/inventory/item/bar
|}

== Query Strings ==
Query strings are a specialized url syntax for representing the contents of a map as an ampersand delimited url query string including the leading '?'. Query string use an open curly brace '{' followed by a percent symbol '%' followed by the name of a dictionary in the replacement context followed by a closing curly brace '}'.

Unlike string substitution, if the named value is not a key in the map contents, the russ directive will be stripped.

{| border="1"
|+ Query String Substitution Examples
! Format !! Map Contents !! Result
|-
| /sql/{$query}{%params}
| { 'query':'get-agent-name-by-id', 'params':{'agent_id':123}}
| /sql/get-agent-name-by-id?agent_id=123
|-
| /proc/{$proc}{%params}
| { 'proc':'messages/dir/DirFindPeople', 'params':{'estate':1, 'query':'designer clothing'}}
| /proc/messages/dir/DirFindPeople?estate=1&query=designer+clothing
|}

== Functions ==
Function substitution uses an open curly brace '{' followed by a bang symbol '!' followed by the name of the substitution function and a closing curly brace '}'. The name is a function that is available to the substitution engine, and may be implementation specific. The function is prototyped as accepting a map context and returning a string.

For example, <b>{!region-host-port}</b> could be a function which takes a map which is assumed to contain a key <code>'region-id'</code>. The function will perform a service lookup for region presence with the region-id in the service builder, and then parse the return document for the region host and port.

== REST Requests ==
For REST Request substitution, the embedded URL is fetched, parsed for a single [[LLSD]] document which is embedded inside the curly braces.

The simple syntax is an opening curly brace '{', followed by the URL, and terminated with a closing curly brace '}'. The document at the url is parsed and treated as a string. Containers, the undefined element, and non-parseable documents are considered errors.

For http request, no instructions to the protocol means to perform a normal GET.

{| border="1"
|+ Rest Request Substitution Examples
! Format !! Results
|-
| <nowiki>{http://gridtool.agni.lindenlab.com/agents/online-now}</nowiki>
| 58582
|-
| <nowiki>{http://blondie.lindenlab.com/lookup/agentname/phoenix/linden||agent-id}</nowiki>
| 3c115e51-04f4-523c-9fa6-98aff1034730
|}

Supported protocols: http, https

We should probably support file.

== Recursive Substitution ==
In theory, this grammar can be used recursively, though only python currently supports this feature.

{| border="1"
|+ Formating Examples
! Format
|-
| <nowiki>{http://sim1028.{$grid}.{$domain}/agent/{$agent-id}/location}</nowiki>
|-
| {{$node}{$domain}}
|}

= Syntax Specification =
The full syntax is an opening curly brace '{', followed by the URL, followed by a vline '|', followed by protocol specific instructions, followed by a 'vline', followed by a path to follow through the document to the element which will be treated as a string.
<pre>
russ-statement : open-russ substitution close-russ
open-russ: '{'
close-russ: '}'
substituion: string-substitution| query-string-substitution | url-substitution | function-substitution
string-substition: '$' llsd-key
query-string-substition: '%' llsd-key
function-substitution: '!' function-name
function-name: llsd-key
url-substitution: url [ vline [ url-parameters ] vline llsd-path]
url: protocol ':' (normal url authority & host & path & parameters & opaque parts)
protocol: 'http' | 'https'
vline: '|'
url-parameters: verb [ body ]
verb: 'GET' | 'PUT' | 'POST' | 'DELETE'
body: ???
llsd-path: segment * [ "/" segment ]
segment: llsd-key
</pre>

Please note that the following elements in the syntax rules are not well defined:
* llsd-key
* body
* function-name

= Implementations =
== python ==
Our indra python libs have a russ implementation in russ.py which supports:
* string substitution
* query string substitution
* url substitution
* recursive substitution

== c++ ==
In indra/llmessage libs has a russ implementation inside of the LLServiceBuilder class which supports:
* string substitution
* url substitution

Recursive URL Substitution Syntax - Revision history

Phoenix Linden: /* Strings */

Phoenix Linden: /* c++ */

Phoenix Linden: New page: Like any substitution syntax, using untrusted formatted strings or untrusted sources of data can lead to exploits. Be careful when designing the usage so that no tainted input winds up in ...