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 <blp@nicira.com>
Acked-by: Justin Pettit <jpettit@nicira.com>

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)

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

ovsdb/jsonrpc-server.c

@@ -1512,8 +1512,8 @@ ovsdb_jsonrpc_monitor_change_cb(const struct ovsdb_row *old,
     return true;
 }
 
-/* Returns JSON for a <row-update> (as described in ovsdb/SPECS) for 'row'
- * within 'mt', or NULL if no row update should be sent.
+/* Returns JSON for a <row-update> (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 <table-updates> 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

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 <database-schema>.  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 <monitor-request> 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 <json-value> 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).

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