{"action":"created","issue":{"url":"https://api.github.com/repos/krpc/krpc/issues/325","repository_url":"https://api.github.com/repos/krpc/krpc","labels_url":"https://api.github.com/repos/krpc/krpc/issues/325/labels{/name}","comments_url":"https://api.github.com/repos/krpc/krpc/issues/325/comments","events_url":"https://api.github.com/repos/krpc/krpc/issues/325/events","html_url":"https://github.com/krpc/krpc/pull/325","id":167524077,"number":325,"title":"Protocol Changes in v0.4.x","user":{"login":"djungelorm","id":6644613,"avatar_url":"https://avatars.githubusercontent.com/u/6644613?v=3","gravatar_id":"","url":"https://api.github.com/users/djungelorm","html_url":"https://github.com/djungelorm","followers_url":"https://api.github.com/users/djungelorm/followers","following_url":"https://api.github.com/users/djungelorm/following{/other_user}","gists_url":"https://api.github.com/users/djungelorm/gists{/gist_id}","starred_url":"https://api.github.com/users/djungelorm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djungelorm/subscriptions","organizations_url":"https://api.github.com/users/djungelorm/orgs","repos_url":"https://api.github.com/users/djungelorm/repos","events_url":"https://api.github.com/users/djungelorm/events{/privacy}","received_events_url":"https://api.github.com/users/djungelorm/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/krpc/krpc/labels/enhancement","name":"enhancement","color":"bfd4f2"},{"url":"https://api.github.com/repos/krpc/krpc/labels/server:api","name":"server:api","color":"c2e0c6"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":{"url":"https://api.github.com/repos/krpc/krpc/milestones/19","html_url":"https://github.com/krpc/krpc/milestones/0.4.0","labels_url":"https://api.github.com/repos/krpc/krpc/milestones/19/labels","id":1740228,"number":19,"title":"0.4.0","description":"","creator":{"login":"djungelorm","id":6644613,"avatar_url":"https://avatars.githubusercontent.com/u/6644613?v=3","gravatar_id":"","url":"https://api.github.com/users/djungelorm","html_url":"https://github.com/djungelorm","followers_url":"https://api.github.com/users/djungelorm/followers","following_url":"https://api.github.com/users/djungelorm/following{/other_user}","gists_url":"https://api.github.com/users/djungelorm/gists{/gist_id}","starred_url":"https://api.github.com/users/djungelorm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djungelorm/subscriptions","organizations_url":"https://api.github.com/users/djungelorm/orgs","repos_url":"https://api.github.com/users/djungelorm/repos","events_url":"https://api.github.com/users/djungelorm/events{/privacy}","received_events_url":"https://api.github.com/users/djungelorm/received_events","type":"User","site_admin":false},"open_issues":8,"closed_issues":4,"state":"open","created_at":"2016-04-30T19:22:35Z","updated_at":"2016-10-15T22:32:35Z","due_on":null,"closed_at":null},"comments":9,"created_at":"2016-07-26T05:29:48Z","updated_at":"2016-10-15T23:07:35Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/krpc/krpc/pulls/325","html_url":"https://github.com/krpc/krpc/pull/325","diff_url":"https://github.com/krpc/krpc/pull/325.diff","patch_url":"https://github.com/krpc/krpc/pull/325.patch"},"body":"Changes to the communication protocol are coming in v0.4.0. These will break backwards compatibility and will require client libraries to be updated. Client _scripts_ are unaffected. The following describes the changes, and the rationale behind them.\r\n\r\nThe new protobuf definitions are available here: https://github.com/krpc/krpc/blob/v0.4.0/protobuf/krpc.proto \r\n\r\nFeedback on the changes is welcome! As this affects third-party clients I'm happy to help update them before it's released. (Paging @TeWu and @Cahu)\r\n\r\nPre-release builds of v0.4.0 are available from the Travis CI server here:\r\nhttp://krpc.s3-website-us-east-1.amazonaws.com/deploy/v0.4.0/\r\n\r\n1. Removing unnecessary message fields\r\n====\r\n\r\nThe following unnecessary fields have been removed (as discussed in #264):\r\n\r\n* ```Response.has_error``` - to check for an error, you can just check if ```Response.error``` is non-empty.\r\n\r\n* ```Response.has_return_value``` - whether a response will have a return value or not is determined by the return type of the procedure, so this information does not need to be sent with every response.\r\n\r\n* ```Parameter.has_default_value``` - to check whether a parameter has a default value, you can check whether ```Parameter.default_value``` is empty.\r\n\r\n* ```Procedure.has_return_type``` - this information is now contained in the return type of the procedure.\r\n\r\n2. Batched RPCs\r\n====\r\n\r\nPreviously, only a single remote call could be sent in a request message. Request messages now support multiple calls, and the corresponding response messages returns the results of the calls.\r\n\r\nThe order of the RPC calls in a request message (`Request.calls`) is the same as the order of the results in the corresponding response message (`Response.results`).\r\n\r\n3. Changes to `GetServices()`\r\n====\r\n\r\nThe ```Services``` message returned by ```KRPC.GetServices()``` was very space inefficient and made it hard for clients to interpret due to its use of type strings and attributes. The following changes have been made to improve this.\r\n\r\n4a. Types\r\n----\r\n\r\nProcedure parameter and return types (the ```Parameter.type``` and ```Procedure.return_type``` protobuf message fields) used to be encoded as strings, for example `int32`, `Class(SpaceCenter.Vessel)` or `List(string)`. These have been changed to use a protobuf message called `Type`, which are defined here: https://github.com/krpc/krpc/blob/v0.4.0/protobuf/krpc.proto#L108\r\n\r\n* The ```Type.code``` field specifies the type. `NONE` is used as the return type for procedures that do not return a value.\r\n\r\n* For ```CLASS``` and ```ENUMERATION``` types the ```Type.service``` and   ```Type.name``` fields will contain the service that defines the class/enum and   the name of the class/enum. For all other types these fields are empty.\r\n\r\n* For collection types the ```Type.types``` repeated field will contain the   sub-types:\r\n\r\n  * ```TUPLE``` types contain 1 or more types in the ```Type.types``` field.\r\n  * ```LIST``` and ```SET``` types contain a single type in the ```Type.types```\r\n    field.\r\n  * ```DICTIONARY``` types contain a 2 types in the ```Type.types```     field - the key and value types, in that order.\r\n  * For all other types the ```Types.types``` field is empty.\r\n\r\nThis representation allows class, enumeration and collection types to be specified directly in the `Type` field for a procedure parameter or return type. They used to be expressed using a combination of a type and an 'attribute'. For example, if a procedure returned a list of integers, it would have return   type `List` and attribute `ReturnType.List(int32)` (both as strings). This is now represented by a single `Type` message, so the attribute is no longer required:\r\n\r\n  ```\r\n  Type {\r\n    code = LIST,\r\n    types = [ Type { code = SINT32 } ]\r\n  }\r\n  ```\r\n\r\nAnd a class type used to be represented by, `ReturnType.Class(ServiceName.ClassName)`. It is now represented by a `Type` message as follows:\r\n\r\n  ```\r\n  Type {\r\n    code = CLASS,\r\n    service = 'ServiceName',\r\n    name = 'ClassName'\r\n  }\r\n  ```\r\n\r\nUsing protobuf messages for types has several benefits:\r\n\r\n- The result of `GetServices()` is _much_ smaller (on the order to 25% smaller for the RPCs currently on the server).\r\n- Types are much easier, and faster, for client libraries to parse. Complex string parsing is no longer required.\r\n\r\n3b. Procedure names\r\n----\r\n\r\nAttributes used to be used to specify whether a procedure is a service procedure, class method, class property, etc. and what class (if any) it belongs to. However, this can be determined from the name of the procedure:\r\n\r\n* 'ProcedureName' - a standard procedure that is just part of a service.\r\n* 'get_PropertyName' - a procedure that returns the value of a property in a service.\r\n* 'set_PropertyName' - a procedure that sets the value of a property in a service.\r\n* 'ClassName_MethodName' - a class method.\r\n* 'ClassName_static_StaticMethodName' - a static class method.\r\n* 'ClassName_get_PropertyName' - a class property getter.\r\n* 'ClassName_set_PropertyName' - a class property setter.\r\n\r\nNote: only letters and numbers are permitted in class/method/property names, so the underscores here can be used to split the name into its constituent parts.\r\n\r\n3c. Attributes\r\n\r\nWith the changes to types and procedure names, the old attributes are unnecessary and so have been removed.\r\n\r\n4. Service definition files\r\n====\r\n\r\nThe service definition JSON files generated by ```krpc-servicedefs``` have also been modified in line with the changes above.\r\n\r\n5. Encoding of signed integers\r\n====\r\n\r\nint32 and int64 types have been changed to use sint32 and sint64. This makes use of protocol buffers' zig zag encoding, which provides a much more compact encoding for negative numbers.\r\n\r\n6. Connecting to the server\r\n====\r\n\r\nThe way clients connect to the server is changing. Currently, to connect, a client sends some magic bytes followed by a client name to the server, then receives a client identifier (that is used to connect to the stream server). The new protocol is as follows:\r\n\r\n- Send a `ConnectionRequest` protobuf message, with the type field set to `RPC`, and containing the (optional) clients name.\r\n- Receive a `ConnectionResponse` protobuf message, containing the clients identifier. This also contains a status field and status message that are populated by the server to indicate if the connection was successful, and if not, why not.\r\n\r\nThe stream server connection protocol works similarly:\r\n- Send a `ConnectionRequest` protobuf message, with the type field set to `STREAM` and client identifier set to the value returned in the connection response when connecting to the RPC server.\r\n- Receive a `ConnectionResponse` protobuf message, and check the status field.\r\n\r\nThis connection protocol is essentially the same as before, but uses protobuf messages to encode the information sent between client and server. This means that the connection request/response messages are extensible (new fields can be added without breaking backwards compatibility) and the client code is made a bit simpler (you can just use the protobuf library to, for example. encode the client name)."},"comment":{"url":"https://api.github.com/repos/krpc/krpc/issues/comments/254016539","html_url":"https://github.com/krpc/krpc/pull/325#issuecomment-254016539","issue_url":"https://api.github.com/repos/krpc/krpc/issues/325","id":254016539,"user":{"login":"djungelorm","id":6644613,"avatar_url":"https://avatars.githubusercontent.com/u/6644613?v=3","gravatar_id":"","url":"https://api.github.com/users/djungelorm","html_url":"https://github.com/djungelorm","followers_url":"https://api.github.com/users/djungelorm/followers","following_url":"https://api.github.com/users/djungelorm/following{/other_user}","gists_url":"https://api.github.com/users/djungelorm/gists{/gist_id}","starred_url":"https://api.github.com/users/djungelorm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djungelorm/subscriptions","organizations_url":"https://api.github.com/users/djungelorm/orgs","repos_url":"https://api.github.com/users/djungelorm/repos","events_url":"https://api.github.com/users/djungelorm/events{/privacy}","received_events_url":"https://api.github.com/users/djungelorm/received_events","type":"User","site_admin":false},"created_at":"2016-10-15T23:07:35Z","updated_at":"2016-10-15T23:07:35Z","body":"As far as I can tell, the python library doesn't have a notion of enum fields being optional. They always have a value. The value is only optional in the binary representation, and if omitted there, is assumed to be set to 0.\r\n\r\nThat default is implicit, so making that change would have no effect. `OK` has a value of 0, and is therefore the default. https://developers.google.com/protocol-buffers/docs/proto3#enum"}}
{"actor":{"display_login":"djungelorm"}}