[tor-bugs] #12944 [Onionoo]: onionoo protocol/client api and base implementaion

[Tor Bug Tracker & Wiki]

#12944: onionoo protocol/client api and base implementaion
-----------------------------+----------------------
     Reporter:  iwakeh       |      Owner:  iwakeh
         Type:  enhancement  |     Status:  assigned
     Priority:  normal       |  Milestone:
    Component:  Onionoo      |    Version:
   Resolution:               |   Keywords:
Actual Points:               |  Parent ID:
       Points:               |
-----------------------------+----------------------

Comment (by iwakeh):

 == Thoughts and ideas

 === Goals and Assumptions
 The {{{protocol}}} package should contain all of onionoo's protocol
 information:
 * resource types,
 * parameters,
 * fields values, and
 * all validation requirements.
 Changes to onionoo's protocol will be reflected in the code of this
 package.
 For example, removal of a parameter can be signaled via deprecating the
 corresponding enum value.

 Classes of {{{server}}} have to "react" to protocol package changes,
 i.e. provide a new document etc.

 * ResourceServlet validates the incoming requests.
 * Hence, ResourceHandler and ResponseBuilder can rely on valid input for
 all methods called from ResourceServlet.


 === The draft of the first part of the protocol-client-api
 Clients that use user input (like koninoo) or some internal
 calculations for querying Onionoo need to verify the input
 or calculated values in order to avoid server errors.

 This first part provides this functionality. The new {{{protocol}}}
 package contains a {{{ResourceType}}} enum, a {{{Parameter}}} enum, and a
 Constants class. The latter is not huge, but I couldn't find a better
 place.
 In order to keep track of the many fields in details docs
 I created an enum {{{FieldValue}}}.

 The subpackage {{{validation}}} provides the classes that implement
 {{{ParameterValidator}}}.

 I adapted the {{{server}}} package and the {{{DetailsDocument}}},
 in order to avoid
 code duplication and make the {{{protocol}}} package the main place
 for protocol changes:

 A new resource has to be added to the Resource enum,
 a new parameter has to be added to the Parameter enum together
 with its ParameterValidator.
 If some parameter or resource is going to be removed, it first
 could be marked as deprecated in these enums and later removed from them.

 (Of course, the RequestHandler still has to be adapted, too, but its
 functionality is not part of the protocol.)

 === Questionable decision
 Well, the enums are lower case reflecting the api. Making them upper case
 constants would require changing case somewhere ...
 I'm undecided about this currently, b/c the code seems more readable the
 lower case way...


 -----

 I attached a patch that passes {{{clean, compile}}}, and {{{test}}} (based
 on the current master and requires java 7).
 It contains some javadoc that needs to be extended.


 ----

 Proceed along these lines?

 ----

 === The next steps
 * provide the protocol part for the documents
 * provide the base client implementation
 * extend tests to directly verify the functionality of the new classes

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/12944#comment:2>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online