From: Ben Pfaff Date: Fri, 4 Apr 2014 16:43:54 +0000 (-0700) Subject: ovsdb: Remove SPECS in favor of referring to RFC 7047. X-Git-Tag: sliver-openvswitch-2.2.90-1~5^2~41 X-Git-Url: http://git.onelab.eu/?p=sliver-openvswitch.git;a=commitdiff_plain;h=c70a77673cfc9e70d4e7e1633bdfa461fbd154f3 ovsdb: Remove SPECS in favor of referring to RFC 7047. Also, add some clarifications relative to RFC 7047 to ovsdb-server(1). Signed-off-by: Ben Pfaff Acked-by: Justin Pettit --- diff --git a/lib/ovsdb-data.c b/lib/ovsdb-data.c index 3aae9f468..0706dd05f 100644 --- a/lib/ovsdb-data.c +++ b/lib/ovsdb-data.c @@ -1,4 +1,4 @@ -/* Copyright (c) 2009, 2010, 2011, 2012 Nicira, Inc. +/* Copyright (c) 2009, 2010, 2011, 2012, 2014 Nicira, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -41,7 +41,7 @@ wrap_json(const char *name, struct json *wrapped) /* Initializes 'atom' with the default value of the given 'type'. * - * The default value for an atom is as defined in ovsdb/SPECS: + * The default value for an atom is as defined in RFC 7047: * * - "integer" or "real": 0 * @@ -409,10 +409,9 @@ ovsdb_atom_from_json__(union ovsdb_atom *atom, * Violations of constraints expressed by 'base' are treated as errors. * * If 'symtab' is nonnull, then named UUIDs in 'symtab' are accepted. Refer to - * ovsdb/SPECS for information about this, and for the syntax that this - * function accepts. If 'base' is a reference and a symbol is parsed, then the - * symbol's 'strong_ref' or 'weak_ref' member is set to true, as - * appropriate. */ + * RFC 7047 for information about this, and for the syntax that this function + * accepts. If 'base' is a reference and a symbol is parsed, then the symbol's + * 'strong_ref' or 'weak_ref' member is set to true, as appropriate. */ struct ovsdb_error * ovsdb_atom_from_json(union ovsdb_atom *atom, const struct ovsdb_base_type *base, @@ -436,8 +435,7 @@ ovsdb_atom_from_json(union ovsdb_atom *atom, /* Converts 'atom', of the specified 'type', to JSON format, and returns the * JSON. The caller is responsible for freeing the returned JSON. * - * Refer to ovsdb/SPECS for the format of the JSON that this function - * produces. */ + * Refer to RFC 7047 for the format of the JSON that this function produces. */ struct json * ovsdb_atom_to_json(const union ovsdb_atom *atom, enum ovsdb_atomic_type type) { @@ -843,7 +841,7 @@ ovsdb_datum_init_empty(struct ovsdb_datum *datum) /* Initializes 'datum' as a datum that has the default value for 'type'. * - * The default value for a particular type is as defined in ovsdb/SPECS: + * The default value for a particular type is as defined in RFC 7047: * * - If n_min is 0, then the default value is the empty set (or map). * @@ -1248,8 +1246,8 @@ ovsdb_datum_from_json__(struct ovsdb_datum *datum, * Violations of constraints expressed by 'type' are treated as errors. * * If 'symtab' is nonnull, then named UUIDs in 'symtab' are accepted. Refer to - * ovsdb/SPECS for information about this, and for the syntax that this - * function accepts. */ + * RFC 7047 for information about this, and for the syntax that this function + * accepts. */ struct ovsdb_error * ovsdb_datum_from_json(struct ovsdb_datum *datum, const struct ovsdb_type *type, @@ -1275,8 +1273,7 @@ ovsdb_datum_from_json(struct ovsdb_datum *datum, * * 'type' constraints on datum->n are ignored. * - * Refer to ovsdb/SPECS for the format of the JSON that this function - * produces. */ + * Refer to RFC 7047 for the format of the JSON that this function produces. */ struct json * ovsdb_datum_to_json(const struct ovsdb_datum *datum, const struct ovsdb_type *type) diff --git a/ovsdb/SPECS b/ovsdb/SPECS deleted file mode 100644 index 5656b9d7f..000000000 --- a/ovsdb/SPECS +++ /dev/null @@ -1,1320 +0,0 @@ - =================================================== - Open vSwitch Configuration Database Specification - =================================================== - -Basic Notation --------------- - -OVSDB uses JSON, as defined by RFC 4627, for its schema format and its -wire protocol format. The JSON implementation in Open vSwitch has the -following limitations: - - - Null bytes (\u0000) are not allowed in strings. - - - Only UTF-8 encoding is supported. (RFC 4627 also mentions - UTF-16BE, UTF-16LE, and UTF-32.) - - - RFC 4627 says that names within a JSON object should be unique. - The Open vSwitch JSON parser discards all but the last value - for a name that is specified more than once. - -The descriptions below use the following shorthand notations for JSON -values. Additional notation is presented later. - - - - A JSON string. Any Unicode string is allowed, as specified by RFC - 4627. Implementations may disallow null bytes. - - - - A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. - - s that begin with _ are reserved to the implementation and may - not be used by the user. - - - - A JSON string that contains a version number that matches - [0-9]+\.[0-9]+\.[0-9]+ - - - - A JSON true or false value. - - - - A JSON number. - - - - A JSON number with an integer value, within a certain range - (currently -2**63...+2**63-1). - - - - Any JSON value. - - - - Any JSON value except null. - - - - A JSON object with the following members: - - "error": required - "details": optional - - The value of the "error" member is a short string, specified in - this document, that broadly indicates the class of the error. - Most "error" strings are specific to contexts described elsewhere - in this document, but the following "error" strings may appear in - any context where an is permitted: - - "error": "resources exhausted" - - The operation requires more resources (memory, disk, CPU, - etc.) than are currently available to the database server. - - "error": "I/O error" - - Problems accessing the disk, network, or other required - resources prevented the operation from completing. - - Database implementations may use "error" strings not specified - in this document to indicate errors that do not fit into any of - the specified categories. - - Optionally, an may include a "details" member, whose value - is a string that describes the error in more detail for the - benefit of a human user or administrator. This document does not - specify the format or content of the "details" string. - - An may also have other members that describe the error in - more detail. This document does not specify the names or values - of these members. - -Schema Format -------------- - -An Open vSwitch configuration database consists of a set of tables, -each of which has a number of columns and zero or more rows. A schema -is represented by , as described below. - - - - A JSON object with the following members: - - "name": required - "version": required - "cksum": optional - "tables": {: , ...} required - - The "name" identifies the database as a whole. It must be - provided to most JSON-RPC requests to identify the database being - operated on. The value of "tables" is a JSON object whose names - are table names and whose values are s. - - The "version" reports the version of the database schema. Because - this is a recent addition to the schema format, OVSDB permits it - to be omitted, but future versions of OVSDB will require it to be - present. Open vSwitch semantics for "version" are described in - ovs-vswitchd.conf.db(5). - - The "cksum" optionally reports an implementation-defined checksum - for the database schema. - - - - A JSON object with the following members: - - "columns": {: , ...} required - "maxRows": optional - "isRoot": optional - "indexes": [*] optional - - The value of "columns" is a JSON object whose names are column - names and whose values are s. - - Every table has the following columns whose definitions are not - included in the schema: - - "_uuid": This column, which contains exactly one UUID value, - is initialized to a random value by the database engine when - it creates a row. It is read-only, and its value never - changes during the lifetime of a row. - - "_version": Like "_uuid", this column contains exactly one - UUID value, initialized to a random value by the database - engine when it creates a row, and it is read-only. However, - its value changes to a new random value whenever any other - field in the row changes. Furthermore, its value is - ephemeral: when the database is closed and reopened, or when - the database process is stopped and then started again, each - "_version" also changes to a new random value. - - If "isRoot" is omitted or specified as false, then any given row - in the table may exist only when there is at least one reference - to it, with refType "strong", from a different row (in the same - table or a different table). This is a "deferred" action: - unreferenced rows in the table are deleted just before transaction - commit. If "isRoot" is specified as true, then rows in the table - exist independent of any references (they can be thought of as - part of the "root set" in a garbage collector). - - For compatibility with schemas created before "isRoot" was - introduced, if "isRoot" is omitted or false in every - in a given , then every table is - part of the root set. - - If "maxRows" is specified, as a positive integer, it limits the - maximum number of rows that may be present in the table. This is - a "deferred" constraint, enforced only at transaction commit time - (see the "transact" request below). If "maxRows" is not - specified, the size of the table is limited only by the resources - available to the database server. "maxRows" constraints are - enforced after unreferenced rows are deleted from tables with a - false "isRoot". - - If "indexes" is specified, it must be an array of zero or more - s. A is an array of one or more strings, - each of which names a column. Each is a set of - columns whose values, taken together within any given row, must be - unique within the table. This is a "deferred" constraint, - enforced only at transaction commit time, after unreferenced rows - are deleted and dangling weak references are removed. Ephemeral - columns may not be part of indexes. - - - - A JSON object with the following members: - - "type": required - "ephemeral": optional - "mutable": optional - - The "type" specifies the type of data stored in this column. - - If "ephemeral" is specified as true, then this column's values are - not guaranteed to be durable; they may be lost when the database - restarts. A column whose type (either key or value) is a strong - reference to a table that is not part of the root set is always - durable, regardless of this value. (Otherwise, restarting the - database could lose entire rows.) - - If "mutable" is specified as false, then this column's values may - not be modified after they are initially set with the "insert" - operation. - - - - The type of a database column. Either an or a JSON - object that describes the type of a database column, with the - following members: - - "key": required - "value": optional - "min": optional - "max": or "unlimited" optional - - If "min" or "max" is not specified, each defaults to 1. If "max" - is specified as "unlimited", then there is no specified maximum - number of elements, although the implementation will enforce some - limit. After considering defaults, "min" must be exactly 0 or - exactly 1, "max" must be at least 1, and "max" must be greater - than or equal to "min". - - If "min" and "max" are both 1 and "value" is not specified, the - type is the scalar type specified by "key". - - If "min" is not 1 or "max" is not 1, or both, and "value" is not - specified, the type is a set of scalar type "key". - - If "value" is specified, the type is a map from type "key" to type - "value". - - - - The type of a key or value in a database column. Either an - or a JSON object with the following members: - - "type": required - "enum": optional - "minInteger": optional, integers only - "maxInteger": optional, integers only - "minReal": optional, reals only - "maxReal": optional, reals only - "minLength": optional, strings only - "maxLength": optional, strings only - "refTable": optional, uuids only - "refType": "strong" or "weak" optional, only with "refTable" - - An by itself is equivalent to a JSON object with a - single member "type" whose value is the . - - "enum" may be specified as a whose type is a set of one - or more values specified for the member "type". If "enum" is - specified, then the valid values of the are limited to - those in the . - - "enum" is mutually exclusive with the following constraints. - - If "type" is "integer", then "minInteger" or "maxInteger" or both - may also be specified, restricting the valid integer range. If - both are specified, then the maxInteger must be greater than or - equal to minInteger. - - If "type" is "real", then "minReal" or "maxReal" or both may also - be specified, restricting the valid real range. If both are - specified, then the maxReal must be greater than or equal to - minReal. - - If "type" is "string", then "minLength" and "maxLength" or both - may be specified, restricting the valid length of value strings. - If both are specified, then maxLength must be greater than or - equal to minLength. String length is measured in characters (not - bytes or UTF-16 code units). - - If "type" is "uuid", then "refTable", if present, must be the name - of a table within this database. If "refTable" is specified, then - "refType" may also be specified. If "refTable" is set, the effect - depends on "refType": - - - If "refType" is "strong" or if "refType" is omitted, the - allowed UUIDs are limited to UUIDs for rows in the named - table. - - - If "refType" is "weak", then any UUIDs are allowed, but - UUIDs that do not correspond to rows in the named table will - be automatically deleted. - - "refTable" constraints are "deferred" constraints: they are - enforced only at transaction commit time (see the "transact" - request below). The other contraints on are - "immediate", enforced immediately by each operation. - - - - One of the strings "integer", "real", "boolean", "string", or - "uuid", representing the specified scalar type. - -Wire Protocol -------------- - -The database wire protocol is implemented in JSON-RPC 1.0. We -encourage use of JSON-RPC over stream connections instead of JSON-RPC -over HTTP, for these reasons: - - * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server - protocol, which is a poor match. Thus, JSON-RPC over HTTP - requires the client to periodically poll the server to receive - server requests. - - * HTTP is more complicated than stream connections and doesn't - provide any corresponding advantage. - - * The JSON-RPC specification for HTTP transport is incomplete. - -We are currently using TCP port 6632 for the database JSON-RPC -connection, but future versions will switch to using IANA-assigned TCP -port 6640. - -The database wire protocol consists of the following JSON-RPC methods: - -list_dbs -........ - -Request object members: - - "method": "list_dbs" required - "params": [] required - "id": required - -Response object members: - - "result": [, ...] - "error": null - "id": same "id" as request - -This operation retrieves an array whose elements are s -that name the databases that can be accessed over this JSON-RPC -connection. - -get_schema -.......... - -Request object members: - - "method": "get_schema" required - "params": [] required - "id": required - -Response object members: - - "result": - "error": null - "id": same "id" as request - -This operation retrieves a that describes hosted -database . - -transact -........ - -Request object members: - - "method": "transact" required - "params": [, *] required - "id": required - -Response object members: - - "result": [*] - "error": null - "id": same "id" as request - -The "params" array for this method consists of a that -identifies the database to which the transaction applies, followed by -zero or more JSON objects, each of which represents a single database -operation. The "Operations" section below describes the valid -operations. - -The value of "id" must be unique among all in-flight transactions -within the current JSON-RPC session. Otherwise, the server may return -a JSON-RPC error. - -The database server executes each of the specified operations in the -specified order, except that if an operation fails, then the remaining -operations are not executed. - -The set of operations is executed as a single atomic, consistent, -isolated transaction. The transaction is committed only if every -operation succeeds. Durability of the commit is not guaranteed unless -the "commit" operation, with "durable" set to true, is included in the -operation set (see below). - -Regardless of whether errors occur, the response is always a JSON-RPC -response with null "error" and a "result" member that is an array with -the same number of elements as "params". Each element of the "result" -array corresponds to the same element of the "params" array. The -"result" array elements may be interpreted as follows: - - - A JSON object that does not contain an "error" member indicates - that the operation completed successfully. The specific members - of the object are specified below in the descriptions of - individual operations. Some operations do not produce any - results, in which case the object will have no members. - - - An , which indicates that the operation completed with an - error. - - - A JSON null value indicates that the operation was not attempted - because a prior operation failed. - -In general, "result" contains some number of successful results, -possibly followed by an error, in turn followed by enough JSON null -values to match the number of elements in "params". There is one -exception: if all of the operations succeed, but the results cannot be -committed, then "result" will have one more element than "params", -with the additional element an . The possible "error" strings -include at least the following: - - "error": "referential integrity violation" - - When the commit was attempted, a column's value referenced the - UUID for a row that did not exist in the table named by the - column's key or value "refTable" that has a - "refType" of "strong". (This can be caused by inserting a row - that references a nonexistent row, by deleting a row that is - still referenced by another row, by specifying the UUID for a - row in the wrong table, and other ways.) - - "error": "constraint violation" - - A column with a key or value "refTable" whose - "refType" is "weak" became empty due to deletion(s) caused - because the rows that it referenced were deleted (or never - existed, if the column's row was inserted within the - transaction), and this column is not allowed to be empty - because its has a "min" of 1. - - "error": "constraint violation" - - The number of rows in a table exceeds the maximum number - permitted by the table's "maxRows" value (see ). - - "error": "constraint violation" - - Two or more rows in a table had the same values in the columns - that comprise an index. - - "error": "resources exhausted" - "error": "I/O error" - - As described in the definition of above. - -If "params" contains one or more "wait" operations, then the -transaction may take an arbitrary amount of time to complete. The -database implementation must be capable of accepting, executing, and -replying to other transactions and other JSON-RPC requests while a -transaction or transactions containing "wait" operations are -outstanding on the same or different JSON-RPC sessions. - -The section "Notation for the Wire Protocol" below describes -additional notation for use with the wire protocol. After that, the -"Operations" section describes each operation. - -cancel -...... - -Request object members: - - "method": "cancel" required - "params": [the "id" for an outstanding request] required - "id": null required - -Response object members: - - - -This JSON-RPC notification instructs the database server to -immediately complete or cancel the "transact" request whose "id" is -the same as the notification's "params" value. - -If the "transact" request can be completed immediately, then the -server sends a response in the form described for "transact", above. -Otherwise, the server sends a JSON-RPC error response of the following -form: - - "result": null - "error": "canceled" - "id": the request "id" member - -The "cancel" notification itself has no reply. - -monitor -....... - -Request object members: - - "method": "monitor" required - "params": [, , ] required - "id": required - - is an object that maps from a table name to an -array of objects. For backward compatibility, a -single may be used instead of an array; it is -treated as a single-element array. - -Each is an object with the following members: - - "columns": [*] optional - "select": optional - - is an object with the following members: - - "initial": optional - "insert": optional - "delete": optional - "modify": optional - -Response object members: - - "result": - "error": null - "id": same "id" as request - -This JSON-RPC request enables a client to replicate tables or subsets -of tables within database . Each element of - specifies a table to be replicated. The JSON-RPC -response to the "monitor" includes the initial contents of each table, -unless disabled (see below). Afterward, when changes to those tables -are committed, the changes are automatically sent to the client using -the "update" monitor notification. This monitoring persists until the -JSON-RPC session terminates or until the client sends a -"monitor_cancel" JSON-RPC request. - -Each describes how to monitor columns in a table: - - The circumstances in which an "update" notification is sent for a - row within the table are determined by : - - If "initial" is omitted or true, every row in the table is - sent as part of the reply to the "monitor" request. - - If "insert" is omitted or true, "update" notifications are - sent for rows newly inserted into the table. - - If "delete" is omitted or true, "update" notifications are - sent for rows deleted from the table. - - If "modify" is omitted or true, "update" notifications are - sent whenever when a row in the table is modified. - - The "columns" member specifies the columns whose values are - monitored. It must not contain duplicates. If "columns" is - omitted, all columns in the table, except for "_uuid", are - monitored. - -If there is more than one in an array of them, then -each in the array should specify both "columns" and -"select", and the "columns" must be non-overlapping sets. - -The "result" in the JSON-RPC response to the "monitor" request is a - object (see below) that contains the contents of the -tables for which "initial" rows are selected. If no tables' initial -contents are requested, then "result" is an empty object. - -update -...... - -Notification object members: - - "method": "update" - "params": [, ] - "id": null - -The in "params" is the same as the value passed as the - in "params" for the "monitor" request. - - is an object that maps from a table name to a -. - -A is an object that maps from the row's UUID (as a -36-byte string) to a object. - -A is an object with the following members: - - "old": present for "delete" and "modify" updates - "new": present for "initial", "insert", and "modify" updates - -This JSON-RPC notification is sent from the server to the client to -tell it about changes to a monitored table (or the initial state of a -modified table). Each table in which one or more rows has changed (or -whose initial view is being presented) is represented in "updates". -Each row that has changed (or whose initial view is being presented) -is represented in its as a member with its name taken -from the row's _uuid member. The corresponding value is a -: - - The "old" member is present for "delete" and "modify" updates. - For "delete" updates, each monitored column is included. For - "modify" updates, the prior value of each monitored column whose - value has changed is included (monitored columns that have not - changed are represented in "new"). - - The "new" member is present for "initial", "insert", and "modify" - updates. For "initial" and "insert" updates, each monitored - column is included. For "modify" updates, the new value of each - monitored column is included. - -monitor_cancel -.............. - -Request object members: - - "method": "monitor_cancel" required - "params": [] required - "id": required - -Response object members: - - "result": {} - "error": null - "id": the request "id" member - -Cancels the ongoing table monitor request, identified by the - in "params" matching the in "params" for an -ongoing "monitor" request. No more "update" messages will be sent for -this table monitor. - -lock operations -............... - -Request object members: - - "method": "lock", "steal", or "unlock" required - "params": [] required - "id": required - -Response object members: - - "result": {"locked": } for "lock" - "result": {"locked": true} for "steal" - "result": {} for "unlock" - "error": null - "id": same "id" as request - -Performs an operation on a "lock" object. The database server -supports an arbitrary number of locks, each of which is identified by -a client-defined id (given in "params"). At any given time, each lock -may have at most one owner. - -The locking operation depends on "method": - - - "lock": The database will assign this client ownership of the - lock as soon as it becomes available. When multiple clients - request the same lock, they will receive it in first-come, first - served order. - - - "steal": The database immediately assigns this client ownership - of the lock. If there is an existing owner, it loses ownership. - - - "unlock": If the client owns the lock, releases it. If the - client is waiting to obtain the lock, cancels the request and - stops waiting. - - (Closing or otherwise disconnecting a database client connection - unlocks all of its locks.) - -For any given lock, the client must alternate "lock" or "steal" -operations with "unlock" operations. That is, if the previous -operation on a lock was "lock" or "steal", it must be followed by an -"unlock" operation, and vice versa. - -For a "lock" operation, the "locked" member in the response object is -true if the lock has already been acquired, false if another client -holds the lock and the client's request for it was queued. In the -latter case, the client will be notified later with a "locked" message -when acquisition succeeds. - -These requests complete and send a response quickly, without waiting. -The "locked" and "stolen" notifications (see below) report -asynchronous changes to ownership. - -The scope of a lock is a database server, not a database hosted by -that server. A naming convention, such as "__", -can effectively limit the scope of a lock to a particular database. - -locked -...... - -Notification object members: - - "method": "locked" - "params": [] - "id": null - -Notifies the client that a "lock" operation that it previously -requested has succeeded. The client now owns the lock named in -"params". - -The database server sends this notification after the reply to the -corresponding "lock" request (but only if the "locked" member of the -response was false), and before the reply to the client's subsequent -"unlock" request. - -stolen -...... - -Notification object members: - - "method": "stolen" - "params": [] - "id": null - -Notifies the client that owns a lock that another database client has -stolen ownership of the lock. The client no longer owns the lock -named in "params". The client must still issue an "unlock" request -before performing any subsequent "lock" or "steal" operation on the -lock. - -If the client originally obtained the lock through a "lock" request, -then it will automatically regain the lock later after the client that -stole it releases it. (The database server will send the client a -"locked" notification at that point to let it know.) - -If the client originally obtained the lock through a "steal" request, -the database server won't automatically reassign it ownership of the -lock when it later becomes available. To regain ownership, the client -must "unlock" and then "lock" or "steal" the lock again. - -echo -.... - -Request object members: - - "method": "echo" required - "params": JSON array with any contents required - "id": required - -Response object members: - - "result": same as "params" - "error": null - "id": the request "id" member - -Both the JSON-RPC client and the server must implement this request. - -This JSON-RPC request and response can be used to implement connection -keepalives, by allowing the server to check that the client is still -there or vice versa. - - -Notation for the Wire Protocol ------------------------------- - - - - An that names a database. The valid s can be - obtained using a "list-db" request. The is taken from - the "name" member of . - - - - An that names a table. - - - - An that names a table column. - - - - A JSON object that describes a table row or a subset of a table - row. Each member is the name of a table column paired with the - of that column. - - - - A JSON value that represents the value of a column in a table row, - one of , a , or a . - - - - A JSON value that represents a scalar value for a column, one of - , , , , . - - - - Either an , representing a set with exactly one element, or - a 2-element JSON array that represents a database set value. The - first element of the array must be the string "set" and the second - element must be an array of zero or more s giving the values - in the set. All of the s must have the same type. - - - - A 2-element JSON array that represents a database map value. The - first element of the array must be the string "map" and the second - element must be an array of zero or more s giving the values - in the map. All of the s must have the same key and value - types. - - (JSON objects are not used to represent because JSON only - allows string names in an object.) - - - - A 2-element JSON array that represents a pair within a database - map. The first element is an that represents the key, the - second element is an that represents the value. - - - - A 2-element JSON array that represents a UUID. The first element - of the array must be the string "uuid" and the second element must - be a 36-character string giving the UUID in the format described - by RFC 4122. For example, the following represents the - UUID 550e8400-e29b-41d4-a716-446655440000: - - ["uuid", "550e8400-e29b-41d4-a716-446655440000"] - - - - A 2-element JSON array that represents the UUID of a row inserted - in an "insert" operation within the same transaction. The first - element of the array must be the string "named-uuid" and the - second element should be the specified as the "uuid-name" - for an "insert" operation within the same transaction. For - example, if an "insert" operation within this transaction - specifies a "uuid-name" of "myrow", the following - represents the UUID created by that operation: - - ["named-uuid", "myrow"] - - A may be used anywhere a is valid. - - - - A 3-element JSON array of the form [, , - ] that represents a test on a column value. - - Except as otherwise specified below, must have the same - type as . - - The meaning depends on the type of : - - integer - real - - must be "<", "<=", "==", "!=", ">=", ">", - "includes", or "excludes". - - The test is true if the column's value satisfies the - relation , e.g. if the column has value - 1 and is 2, the test is true if is "<", - "<=" or "!=", but not otherwise. - - "includes" is equivalent to "=="; "excludes" is equivalent - to "!=". - - boolean - string - uuid - - must be "!=", "==", "includes", or "excludes". - - If is "==" or "includes", the test is true if - the column's value equals . If is "!=" - or "excludes", the test is inverted. - - set - map - - must be "!=", "==", "includes", or "excludes". - - If is "==", the test is true if the column's - value contains exactly the same values (for sets) or pairs - (for maps). If is "!=", the test is inverted. - - If is "includes", the test is true if the - column's value contains all of the values (for sets) or - pairs (for maps) in . The column's value may also - contain other values or pairs. - - If is "excludes", the test is true if the - column's value does not contain any of the values (for - sets) or pairs (for maps) in . The column's value - may contain other values or pairs not in . - - If is "includes" or "excludes", then the - required type of is slightly relaxed, in that it - may have fewer than the minimum number of elements - specified by the column's type. If is - "excludes", then the required type is additionally relaxed - in that may have more than the maximum number of - elements specified by the column's type. - - - - One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". - - - - A 3-element JSON array of the form [, , ] - that represents a change to a column value. - - Except as otherwise specified below, must have the same - type as . - - The meaning depends on the type of : - - integer - real - - must be "+=", "-=", "*=", "/=" or (integer only) - "%=". The value of is changed to the sum, - difference, product, quotient, or remainder, respectively, - of and . - - Constraints on are ignored when parsing . - - boolean - string - uuid - - No valid s are currently defined for these types. - - set - - Any valid for the set's element type may be - applied to the set, in which case the mutation is applied - to each member of the set individually. must be a - scalar value of the same type as the set's element type, - except that contraints are ignored. - - If is "insert", then each of the values in the - set in is added to if it is not already - present. The required type of is slightly - relaxed, in that it may have fewer than the minimum number - of elements specified by the column's type. - - If is "delete", then each of the values in the - set in is removed from if it is present - there. The required type is slightly relaxed in that - may have more or less than the maximum number of - elements specified by the column's type. - - map - - must be "insert" or "delete". - - If is "insert", then each of the key-value pairs - in the map in is added to only if its key - is not already present. The required type of is - slightly relaxed, in that it may have fewer than the - minimum number of elements specified by the column's type. - - If is "delete", then may have the same - type as (a map type) or it may be a set whose - element type is the same as 's key type: - - - If is a map, the mutation deletes each - key-value pair in whose key and value equal - one of the key-value pairs in . - - - If is a set, the mutation deletes each - key-value pair in whose key equals one of - the values in . - - For "delete", may have any number of elements, - regardless of restrictions on the number of elements in - . - - - - One of "+=", "-=", "*=", "/=", "%=", "insert", "delete". - -Operations ----------- - -Each of the available operations is described below. - -insert -...... - -Request object members: - - "op": "insert" required - "table":
required - "row": required - "uuid-name": optional - -Result object members: - - "uuid": - -Semantics: - - Inserts "row" into "table". - - If "row" does not specify values for all the columns in "table", - those columns receive default values. The default value for a - column depends on its type. The default for a column whose - specifies a "min" of 0 is an empty set or empty map. Otherwise, - the default is a single value or a single key-value pair, whose - value(s) depend on its : - - - "integer" or "real": 0 - - - "boolean": false - - - "string": "" (the empty string) - - - "uuid": 00000000-0000-0000-0000-000000000000 - - The new row receives a new, randomly generated UUID. - - If "uuid-name" is supplied, then it is an error if is not - unique among the "uuid-name"s supplied on all the "insert" - operations within this transaction. - - The UUID for the new row is returned as the "uuid" member of the - result. - -Errors: - - "error": "duplicate uuid-name" - - The same "uuid-name" appears on another "insert" operation - within this transaction. - - "error": "constraint violation" - - One of the values in "row" does not satisfy the immediate - constraints for its column's . This error will - occur for columns that are not explicitly set by "row" if the - default value does not satisfy the column's constraints. - -select -...... - -Request object members: - - "op": "select" required - "table":
required - "where": [*] required - "columns": [*] optional - -Result object members: - - "rows": [*] - -Semantics: - - Searches "table" for rows that match all the conditions specified - in "where". If "where" is an empty array, every row in "table" is - selected. - - The "rows" member of the result is an array of objects. Each - object corresponds to a matching row, with each column - specified in "columns" as a member, the column's name as the - member name and its value as the member value. If "columns" - is not specified, all the table's columns are included. If - two rows of the result have the same values for all included - columns, only one copy of that row is included in "rows". - Specifying "_uuid" within "columns" will avoid dropping - duplicates, since every row has a unique UUID. - - The ordering of rows within "rows" is unspecified. - -update -...... - -Request object members: - - "op": "update" required - "table":
required - "where": [*] required - "row": required - -Result object members: - - "count": - -Semantics: - - Updates rows in a table. - - Searches "table" for rows that match all the conditions - specified in "where". For each matching row, changes the - value of each column specified in "row" to the value for that - column specified in "row". - - The "_uuid" and "_version" columns of a table may not be directly - updated with this operation. Columns designated read-only in the - schema also may not be updated. - - The "count" member of the result specifies the number of rows - that matched. - -Errors: - - "error": "constraint violation" - - One of the values in "row" does not satisfy the immediate - constraints for its column's . -mutate -...... - -Request object members: - - "op": "mutate" required - "table":
required - "where": [*] required - "mutations": [*] required - -Result object members: - - "count": - -Semantics: - - Mutates rows in a table. - - Searches "table" for rows that match all the conditions specified - in "where". For each matching row, mutates its columns as - specified by each in "mutations", in the order - specified. - - The "_uuid" and "_version" columns of a table may not be directly - modified with this operation. Columns designated read-only in the - schema also may not be updated. - - The "count" member of the result specifies the number of rows - that matched. - -Errors: - - "error": "domain error" - - The result of the mutation is not mathematically defined, - e.g. division by zero. - - "error": "range error" - - The result of the mutation is not representable within the - database's format, e.g. an integer result outside the range - INT64_MIN...INT64_MAX or a real result outside the range - -DBL_MAX...DBL_MAX. - - "error": "constraint violation" - - The mutation caused the column's value to violate a - constraint, e.g. it caused a column to have more or fewer - values than are allowed, an arithmetic operation caused a set - or map to have duplicate elements, or it violated a constraint - specified by a column's . - -delete -...... - -Request object members: - - "op": "delete" required - "table":
required - "where": [*] required - -Result object members: - - "count": - -Semantics: - - Deletes all the rows from "table" that match all the conditions - specified in "where". - - The "count" member of the result specifies the number of deleted - rows. - -wait -.... - -Request object members: - - "op": "wait" required - "timeout": optional - "table":
required - "where": [*] required - "columns": [*] required - "until": "==" or "!=" required - "rows": [*] required - -Result object members: - - none - -Semantics: - - Waits until a condition becomes true. - - If "until" is "==", checks whether the query on "table" specified - by "where" and "columns", which is evaluated in the same way as - specified for "select", returns the result set specified by - "rows". If it does, then the operation completes successfully. - Otherwise, the entire transaction rolls back. It is automatically - restarted later, after a change in the database makes it possible - for the operation to succeed. The client will not receive a - response until the operation permanently succeeds or fails. - - If "until" is "!=", the sense of the test is negated. That is, as - long as the query on "table" specified by "where" and "columns" - returns "rows", the transaction will be rolled back and restarted - later. - - If "timeout" is specified, then the transaction aborts after the - specified number of milliseconds. The transaction is guaranteed - to be attempted at least once before it aborts. A "timeout" of 0 - will abort the transaction on the first mismatch. - -Errors: - - "error": "not supported" - - One or more of the columns in this table do not support - triggers. This error will not occur if "timeout" is 0. - - "error": "timed out" - - The "timeout" was reached before the transaction was able to - complete. - -commit -...... - -Request object members: - - "op": "commit" required - "durable": required - -Result object members: - - none - -Semantics: - - If "durable" is specified as true, then the transaction, if it - commits, will be stored durably (to disk) before the reply is sent - to the client. - -Errors: - - "error": "not supported" - - When "durable" is true, this database implementation does not - support durable commits. - -abort -..... - -Request object members: - - "op": "abort" required - -Result object members: - - (never succeeds) - -Semantics: - - Aborts the transaction with an error. This may be useful for - testing. - -Errors: - - "error": "aborted" - - This operation always fails with this error. - -comment -....... - - -Request object members: - - "op": "comment" required - "comment": required - -Result object members: - - none - -Semantics: - - Provides information to a database administrator on the purpose of - a transaction. The OVSDB server, for example, adds comments in - transactions that modify the database to the database journal. - -assert -...... - -Request object members: - - "op": "assert" required - "lock": required - -Result object members: - - none - -Semantics: - - If the client does not own the lock named , aborts the - transaction. - -Errors: - - "error": "not owner" - - The client does not own the named lock. diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk index dfb900a2b..404848e1b 100644 --- a/ovsdb/automake.mk +++ b/ovsdb/automake.mk @@ -65,7 +65,6 @@ DISTCLEANFILES += ovsdb/ovsdb-server.1 MAN_ROOTS += ovsdb/ovsdb-server.1.in # ovsdb-idlc -EXTRA_DIST += ovsdb/SPECS noinst_SCRIPTS += ovsdb/ovsdb-idlc EXTRA_DIST += ovsdb/ovsdb-idlc.in MAN_ROOTS += ovsdb/ovsdb-idlc.1 diff --git a/ovsdb/jsonrpc-server.c b/ovsdb/jsonrpc-server.c index 692830c0c..cfaa656c0 100644 --- a/ovsdb/jsonrpc-server.c +++ b/ovsdb/jsonrpc-server.c @@ -1512,8 +1512,8 @@ ovsdb_jsonrpc_monitor_change_cb(const struct ovsdb_row *old, return true; } -/* Returns JSON for a (as described in ovsdb/SPECS) for 'row' - * within 'mt', or NULL if no row update should be sent. +/* Returns JSON for a (as described in RFC 7047) for 'row' within + * 'mt', or NULL if no row update should be sent. * * The caller should specify 'initial' as true if the returned JSON is going to * be used as part of the initial reply to a "monitor" request, false if it is @@ -1596,9 +1596,9 @@ ovsdb_jsonrpc_monitor_compose_row_update( } /* Constructs and returns JSON for a object (as described in - * ovsdb/SPECS) for all the outstanding changes within 'monitor', and deletes - * all the outstanding changes from 'monitor'. Returns NULL if no update needs - * to be sent. + * RFC 7047) for all the outstanding changes within 'monitor', and deletes all + * the outstanding changes from 'monitor'. Returns NULL if no update needs to + * be sent. * * The caller should specify 'initial' as true if the returned JSON is going to * be used as part of the initial reply to a "monitor" request, false if it is diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in index a4cf3442d..15382b486 100644 --- a/ovsdb/ovsdb-server.1.in +++ b/ovsdb/ovsdb-server.1.in @@ -183,6 +183,54 @@ the command line or through the \fBovsdb\-server/add\-db\fR command. .so lib/vlog-unixctl.man .so lib/memory-unixctl.man .so lib/coverage-unixctl.man +.SH "SPECIFICATIONS" +. +.PP +\fBovsdb\-server\fR implements the Open vSwitch Database (OVSDB) +protocol specified in RFC 7047, with the following clarifications: +. +.IP "3.1. JSON Usage" +RFC 4627 says that names within a JSON object should be unique. +The Open vSwitch JSON parser discards all but the last value +for a name that is specified more than once. +. +.IP "3.2. Schema Format" +RFC 7047 requires the "version" field in . Current +versions of \fBovsdb\-server\fR allow it to be omitted (future +versions are likely to require it). +. +.IP "4. Wire Protocol" +The original OVSDB specifications included the following reason, +omitted from RFC 7047, to operate JSON-RPC directly over a stream +instead of over HTTP: +. +.RS +.IP \(bu +JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server +protocol, which is a poor match. Thus, JSON-RPC over HTTP requires +the client to periodically poll the server to receive server requests. +.IP \(bu +HTTP is more complicated than stream connections and doesn't provide +any corresponding advantage. +.IP \(bu +The JSON-RPC specification for HTTP transport is incomplete. +.RE +. +.IP "4.1.5. Monitor" +For backward compatibility, \fBovsdb\-server\fR currently permits a +single to be used instead of an array; it is treated +as a single-element array. Future versions of \fBovsdb\-server\fR +might remove this compatibility feature. +.IP +Because the parameter is used to match subsequent update +notifications (see below) to the request, it must be unique among all +active monitors. \fBovsdb\-server\fR rejects attempt to create two +monitors with the same identifier. +. +.IP "6. IANA Considerations" +\fBovsdb\-server\fR currently defaults to its historical port number +6632. Future versions will adopt IANA-assigned port 6640 as default. + .SH "SEE ALSO" . .BR ovsdb\-tool (1). diff --git a/python/ovs/db/data.py b/python/ovs/db/data.py index e21a1ccfa..6baff38ba 100644 --- a/python/ovs/db/data.py +++ b/python/ovs/db/data.py @@ -1,4 +1,4 @@ -# Copyright (c) 2009, 2010, 2011 Nicira, Inc. +# Copyright (c) 2009, 2010, 2011, 2014 Nicira, Inc. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -307,7 +307,7 @@ class Datum(object): Violations of constraints expressed by 'type' are treated as errors. If 'symtab' is nonnull, then named UUIDs in 'symtab' are accepted. - Refer to ovsdb/SPECS for information about this, and for the syntax + Refer to RFC 7047 for information about this, and for the syntax that this function accepts.""" is_map = type_.is_map() if (is_map or