Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with ====Digest==== Digest authentication is used since Version 8.0}}: As unsalted md5 hashes can easily be uncovered usingrainbow tables, a light-weight variant of digest authentication is now used forclient/server communication:
====Legacy: cramCRAM-MD5 was discarded, because unsalted md5====hashes could easily be uncoveredusing rainbow tables. However, most client bindings still provide support forthe outdated handshaking, as it only slightly differs from the new protocol:
|-
| WATCH
| <code>\10 {name}</code>
| <code>{info} \0</code>
| Registers the client for the specified event.
|-
| UNWATCH
| <code>\11 {name}</code>
| <code>{info} \0</code>
| Unregisters the client.
{{Mark|Since Version 8.0}}, also Also sequences can be bound to variables and the context:
* Watch the specified event:<br/><code>void watch(String name, Event notifier)</code>
* Unwatch the specified event:<br/><code>void unwatch(String name)</code>
[[Category:Developer]]
[[Category:Server]]
[[Category:API]]
no edit summary
===Conventions===
* <code>\xxx</code>: single byte.* <code>{...}</code>: utf8 strings or raw data, suffixed with a <code>\000</code> byte. To avoid confusion with this end-of-string byte, all transfered <code>\000</code> and <code>\FF</code> bytes that occur in raw data will be are prefixed with by an additional <code>\FF</code>byte.
===Authentication===
# Client connects to server socket
# Server sends a '''realm ''' and '''nonce''', separated by a colon: <code>{realm:nonce}</code># Client sends the '''user name ''' and a hash value. The hash is composed of the md5 hash of## the md5 hash of the '''user name''', '''realm ''', and '''password ''' (all separated by a colon), and## the server '''nonce''': <code>{username} {md5(md5(username:realm:password) + nonce)}</code># Server replies with <code>\000</code> (success) or <code>\101</code> (error) ====CRAM-MD5====
# Client connects to server socket
# Server sends a '''nonce ''' (timestamp): <code>{nonce}</code># Client sends the '''user name ''' and a hash value. The hash is composed of the md5 hash of## the md5 of the '''password ''' and## the server '''nonce''': <code>{username} {md5(md5(password) + nonce)}</code># Server replies with <code>\000</code> (success) or <code>\101</code> (error)
Clients can easily be implemented to both support {{Code|digest}} and {{Code|cram-md5}} authentication: If the first server response contains no colon, {{Code|cram-md5}} should be chosen.
| COMMAND
| <code>{command}</code>
| <code>{result} {info} \000</code>
| Executes a database command.
|-
| QUERY
| <code>\0 00 {query}</code>| <code>{id} \000</code>
| Creates a new query instance and returns its id.
|-
| CREATE
| <code>\8 08 {name} {input}</code>| <code>{info} \000</code>
| Creates a new database with the specified input (may be empty).
|-
| ADD
| <code>\9 09 {name} {path} {input}</code>| <code>{info} \000</code>
| Adds a new resource to the opened database.
|-
| REPLACE
| <code>\12 0C {path} {input}</code>| <code>{info} \000</code>
| Replaces a resource with the specified input.
|-
| STORE
| <code>\13 0D {path} {input}</code>| <code>{info} \000</code>
| Stores a binary resource in the opened database.
|-
| ↯ error
| <code></code>
| <code>{</code>''partial result''<code>} {error} \101</code>
| Error feedback.
|}
|-
| CLOSE
| <code>\2 02 {id}</code>| <code>\0 00 \000</code>
| Closes and unregisters the query with the specified id.
|-
| BIND
| <code>\3 03 {id} {name} {value} {type}</code>| <code>\0 00 \000</code>
| Binds a value to a variable. The type will be ignored if the string is empty.
|-
| RESULTS
| <code>\4 04 {id}</code>| <code>\x xx {item} ... \x xx {item} \000</code>| Returns all resulting items as strings, prefixed by a single byte ({{Code|\xxx}}) that represents the [[Server Protocol: Types|Type ID]]. This command is called by the {{Code|more()}} function of a client implementation.
|-
| EXECUTE
| <code>\5 05 {id}</code>| <code>{result} \000</code>| Executes the query and returns all results the result as a single string.
|-
| INFO
| <code>\6 06 {id}</code>| <code>{result} \000</code>
| Returns a string with query compilation and profiling info.
|-
| OPTIONS
| <code>\7 07 {id}</code>| <code>{result} \000</code>| Returns a string with all query serialization parameters, which can e.g. be assigned to the [[Options#SERIALIZER|SERIALIZER]] option.
|-
| CONTEXT
| <code>\14 0E {id} {value} {type}</code>| <code>\0 00 \000</code>
| Binds a value to the context. The type will be ignored if the string is empty.
|-
| UPDATING
| <code>\30 1E {id}</code>| <code>{result} \000</code>| Returns {{Code|true}} if the query may perform updatescontains updating expressions; {{Code|false}} otherwise.
|-
| FULL
| <code>\31 1F {id}</code>| <code>''XDM'' {item} ... ''XDM'' {item} \000</code>
| Returns all resulting items as strings, prefixed by the [[Server Protocol: Types#XDM Meta Data|XDM Meta Data]]. This command is e. g. used by the [[Developing|XQJ API]].
|}
As can be seen in the table, all results end with a single {{Code|\000}} byte, which indicates that the process was successful. If an error occurs, an additional byte {{Code|\101}} is sent, which is then followed by the {{Code|error}} message string.
====Binding Sequences====
* {{Code|empty-sequence()}} must be supplied as type if an empty sequence is to be bound.
* Multiple items are supplied via the <code>{value}</code> argument and separated with {{Code|\101}} bytes.* Item types are specified by appending {{Code|\202}} and the type in its string representation to an item. If no item type is specified, the general type is used.
Some examples for the <code>{value}</code> argument:
* the two integers {{Code|123}} and {{Code|789}} are encoded as {{Code|123}}, {{Code|\101}}, {{Code|789}} and {{Code|\000}} ({{Code|xs:integer}} may be specified via the <code>{type}</code> argument).* the two items {{Code|xs:integer(123)}} and {{Code|xs:string('ABC')}} are encoded as {{Code|123}}, {{Code|\202}}, {{Code|xs:integer}}, {{Code|\101}}, {{Code|ABC}}, {{Code|\202}}, {{Code|xs:string}} and {{Code|\000}}.
==Example==
* '''Client''' connects to the database server socket
* '''Server''' sends realm and timestamp "BaseX:1369578179679": {{Code|◄ 42 61 73 65 58 3A 31 33 36 39 35 37 38 31 37 39 36 37 39 00}}
* '''Client''' sends user name "jack": {{Code|6A 61 63 6B 00 ►}}
* '''Client''' additionally sends hashed password/timestamp combinationhash: md5(md5("jack:BaseX:topsecret") + "1369578179679") = "66442c0e3b5af8b9324f7e31b7f5cca8ca664a31f8deda9b71ea3e79347f6666": {{Code|63 61 36 36 34 ... 00 ►}}
* '''Server''' replies with success code: {{Code|◄ 00}}
* '''Client''' sends the "INFO" command: {{Code|49 4E 46 4F 00 ►}}
* '''Client''' requests the query results via the RESULTS protocol command and its query id: {{Code|04 31 00 ►}}
* '''Server''' returns the first result ("1", type xs:integer): {{Code|◄ 52 31 00}}
* '''Server''' sends a single "{{Code|\0" 00}} byte instead of a new result, which indicates that no more results can be expected: {{Code|◄ 00}}* '''Server''' sends the error code "{{Code|\1" 01}} and the error message ("Stopped at..."): {{Code|◄ 01 53 74 6f ... 00}}
* '''Client''' closes the query instance: {{Code|02 31 00 ►}}
* '''Server''' sends a response (which is equal to an empty info string) and success code: {{Code|◄ 00 00}}
* Store raw data at the specified path:<br/><code>void store(String path, InputStream input)</code>
* Return process information:<br/><code>String info()</code>
=Changelog=
;Version 8.2
* Removed: {{Code|WATCH}} and {{Code|UNWATCH}} command
;Version 8.0
</div>
