commit f04a923ecccb1dbcdcfbe3cb7da4e24a331a1422 Author: Karsten Loesing <karsten.loesing@gmx.net> Date: Tue Sep 16 15:39:51 2014 +0200 Add next_major_version_scheduled field. Discussed with iwakeh in #12905. --- ChangeLog | 8 +- .../torproject/onionoo/server/ResponseBuilder.java | 16 +++- web/protocol.html | 90 +++++++++++++++++++- 3 files changed, 105 insertions(+), 9 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2a1fe71..533541b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,12 @@ Changes in version ?.?.? - 2014-??-?? + o Minor protocol changes: + - Add optional field "next_major_version_scheduled", changing protocol + version to 1.1. Implements #12905. + Changes in version 1.0.0 - 2014-09-16 - - First assigned version number. + + o Major protocol changes. + - First assigned version number. diff --git a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java index c951fd3..d304c4d 100644 --- a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java +++ b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java @@ -69,12 +69,20 @@ public class ResponseBuilder { return this.charsWritten; } - private static final String PROTOCOL_VERSION = "1.0"; + private static final String PROTOCOL_VERSION = "1.1"; + + private static final String NEXT_MAJOR_VERSION_SCHEDULED = null; private void writeRelays(List<SummaryDocument> relays, PrintWriter pw) { - String header = "{\"version\":\"" + PROTOCOL_VERSION - + "\",\n\"relays_published\":\"" + relaysPublishedString - + "\",\n\"relays\":["; + String nextMajorVersionScheduledLine = + NEXT_MAJOR_VERSION_SCHEDULED == null + ? "" + : String.format("\"next_major_version_scheduled\":\"%s\",\n", + NEXT_MAJOR_VERSION_SCHEDULED); + String header = String.format("{\"version\":\"%s\",\n" + + "%s\"relays_published\":\"%s\",\n\"relays\":[", + PROTOCOL_VERSION, nextMajorVersionScheduledLine, + relaysPublishedString); this.charsWritten += header.length(); pw.write(header); int written = 0; diff --git a/web/protocol.html b/web/protocol.html index 9a46c9e..e55d167 100644 --- a/web/protocol.html +++ b/web/protocol.html @@ -135,8 +135,8 @@ If you want to be informed of upcoming protocol changes, subscribe to the mailing list. </p> -<p>All responses contain a "version" string that indicates whether clients -know whether they can parse the document or not. +<p>All responses contain a <strong>"version"</strong> string that +indicates whether clients can parse the document or not. Version strings consist of a major and a minor version number. The major version number is raised when previously required fields are dropped or turned into optional fields, when request parameters or @@ -147,12 +147,22 @@ If clients support the same major version given in a response but only a lower minor version, they should be able to parse the document but may not understand all fields. If clients support a lower major version, they should not attempt to parse -a document, because there may be backward-incompatible changes. -The following versions have been used in the past six months:</p> +a document, because there may be backward-incompatible changes.</p> + +<p>Responses may also contain the optional +<strong>"next_major_version_scheduled"</strong> field that announces when +the next major version is scheduled to be deployed. +Clients should inform their users that they should upgrade to the next +major protocol version before the provided date.</p> + +<p>The following versions have been used in the past six months or are +scheduled to be deployed in the next months:</p> <ul> <li><strong>1.0</strong>: First assigned version number on August 31, 2014.</li> +<li><strong>1.1</strong>: Added optional "next_major_version_scheduled" +field on September 16, 2014.</li> </ul> </div> <!-- box --> @@ -502,6 +512,18 @@ Onionoo protocol version string. </li> <li> +<font color="blue"><b>next_major_version_scheduled</b></font> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +<font color="blue">Added on September 16, 2014.</font> +</p> +</li> + +<li> <b>relays_published</b> <code class="typeof">string</code> <span class="required-true">required</span> @@ -665,6 +687,18 @@ Onionoo protocol version string. </li> <li> +<font color="blue"><b>next_major_version_scheduled</b></font> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +<font color="blue">Added on September 16, 2014.</font> +</p> +</li> + +<li> <b>relays_published</b> <code class="typeof">string</code> <span class="required-true">required</span> @@ -1450,6 +1484,18 @@ Onionoo protocol version string. </li> <li> +<font color="blue"><b>next_major_version_scheduled</b></font> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +<font color="blue">Added on September 16, 2014.</font> +</p> +</li> + +<li> <b>relays_published</b> <code class="typeof">string</code> <span class="required-true">required</span> @@ -1623,6 +1669,18 @@ Onionoo protocol version string. </li> <li> +<font color="blue"><b>next_major_version_scheduled</b></font> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +<font color="blue">Added on September 16, 2014.</font> +</p> +</li> + +<li> <b>relays_published</b> <code class="typeof">string</code> <span class="required-true">required</span> @@ -1828,6 +1886,18 @@ Onionoo protocol version string. </li> <li> +<font color="blue"><b>next_major_version_scheduled</b></font> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +<font color="blue">Added on September 16, 2014.</font> +</p> +</li> + +<li> <b>relays_published</b> <code class="typeof">string</code> <span class="required-true">required</span> @@ -2006,6 +2076,18 @@ Onionoo protocol version string. </li> <li> +<font color="blue"><b>next_major_version_scheduled</b></font> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +<font color="blue">Added on September 16, 2014.</font> +</p> +</li> + +<li> <b>relays_published</b> <code class="typeof">string</code> <span class="required-true">required</span>