Updating documentation and deprecating old APIs

README.md

@@ -46,6 +46,8 @@
     </li>
     <li><a href="#usage">Usage</a></li>
     <li><a href="#building">Building</a></li>
+    <li><a href="#performance">Performance</a></li>
+    <li><a href="#additional-documentation">Additional Documentation</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
     <li><a href="#contact">Contact</a></li>
@@ -88,18 +90,30 @@ Data is usually exchanged with ECUs by means of a CAN bus or Ethernet based prot
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-<!-- KUKSA ANALYSIS -->
-## Kuksa analysis
-Extended [Kuksa analysis](./doc/kuksa_analysis.md) containing functional requirements, use cases diagrams, latest and new API definition `kuksa.val.v2` as well as new design discussions for future developments and improvements.
-
 ### APIs supported by Databroker
 
-Kuksa Databroker implements the following service interfaces:
+Kuksa Databroker provides [gRPC](https://grpc.io/) based API endpoints which can be used by
+clients to interact with the server. gRPC services are specified by means of `.proto` files which define the services and the data
+exchanged between server and client.
+[Tooling](https://grpc.io/docs/languages/) is available for most popular programming languages to create
+client stubs for invoking the services.
+The Databroker uses gRPC's default HTTP/2 transport and [protocol buffers](https://developers.google.com/protocol-buffers) for message serialization.
+The same `.proto` file can be used to generate server skeleton and client stubs for other transports and serialization formats as well.
 
-- Enabled on Databroker by default [kuksa.val.v2.VAL](proto/kuksa/val/v2/val.proto) (recommended to use)
-- Enabled on Databroker by default [kuksa.val.v1.VAL](proto/kuksa/val/v1/val.proto)
-- Disabled on Databroker by default [sdv.databroker.v1.Broker](proto/sdv/databroker/v1/broker.proto)
-- Disabled on Databroker by default [sdv.databroker.v1.Collector](proto/sdv/databroker/v1/collector.proto)
+HTTP/2 is a binary replacement for HTTP/1.1 used for handling connections, multiplexing (channels) and providing a standardized way to add headers for authorization and TLS for encryption/authentication.
+It also supports bi-directional streaming between client and server.
+
+Kuksa Databroker implements the following gRPC service interfaces:
+
+- Enabled on Databroker by default [kuksa.val.v2.VAL](proto/kuksa/val/v2/val.proto)
+- Enabled on Databroker by default [kuksa.val.v1.VAL](proto/kuksa/val/v1/val.proto) (Deprecated!)
+- Disabled on Databroker by default [sdv.databroker.v1.Broker](proto/sdv/databroker/v1/broker.proto) (Deprecated!)
+- Disabled on Databroker by default [sdv.databroker.v1.Collector](proto/sdv/databroker/v1/collector.proto) (Deprecated!)
+
+In addition to the gRPC interfaces the Kuksa Databroker also supports a subset of the [COVESA VISS v2 Protocol[(https://github.com/COVESA/vehicle-information-service-specification)
+using WebSocket.
+Please visit the [user guide](doc/user_guide.md) for more information on how the interfaces can be enabled and configured in the Databroker.
+Please visit the [protocol documentation](doc/protocol.md) for more information on the APIs.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -130,7 +144,7 @@ The quickest possible way to get Kuksa Databroker up and running.
    > :bulb: **Tip:** You can stop the container using `ctrl-c`.
 
 *Note that not all APIs are enabled by default, see [user guide](doc/user_guide.md) and*
-*[protocols](doc/protocol/README.md) for more information!*
+*[protocols](doc/protocol.md) for more information!*
 
 ### Reading and writing VSS data using the CLI
 
@@ -277,12 +291,23 @@ Signal Consumer(stream subscribe) <- Databroker <- Provider(stream publish)
 
 Feel free to use it and share your results with us!
 
+## Additional Documentation
+
+Additional documentation is available in the [repository documentation folder](doc).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ## Contributing
 
 Please refer to the [Kuksa Contributing Guide](CONTRIBUTING.md).
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+
+<!-- KUKSA ANALYSIS -->
+## Kuksa analysis
+Extended [Kuksa analysis](./doc/kuksa_analysis.md) containing functional requirements, use cases diagrams, latest and new API definition `kuksa.val.v2` as well as new design discussions for future developments and improvements.
+
 ## License
 
 Kuksa Databroker is provided under the terms of the [Apache Software License 2.0](LICENSE).

databroker/src/grpc/kuksa_val_v2/val.rs

@@ -2368,7 +2368,9 @@ mod tests {
             .await
             .map(|res| res.into_inner())
         {
-            Ok(_) => {}
+            Ok(_) => {
+                panic!("We shall not succeed with a blank before *")
+            }
             Err(error) => {
                 assert_eq!(
                     error.code(),
@@ -2397,7 +2399,9 @@ mod tests {
             .await
             .map(|res| res.into_inner())
         {
-            Ok(_) => {}
+            Ok(_) => {
+                panic!("Success not expected!")
+            }
             Err(error) => {
                 assert_eq!(error.code(), tonic::Code::NotFound, "unexpected error code");
                 assert_eq!(

doc/QUERY.md

@@ -1,4 +1,7 @@
-# 1. Data Broker Query Syntax
+# 1. Databroker sdv.databroker.v1 Query Syntax
+
+*Note! This document is only relevant for the [sdv.databroker.v1](../proto/sdv/databroker/v1) API!*
+
 
 - [1. Data Broker Query Syntax](#1-data-broker-query-syntax)
   - [1.1. Intro](#11-intro)

doc/README.md

@@ -0,0 +1,19 @@
+# KUKSA Documentation
+
+This folder contain various documents related to KUKSA
+
+Document  | Content/Comment
+----------|--------------------
+[Eclipse Kuksa™ Databroker User Guide](user_guide.md) | Guide on how to start and configure Kuksa Databroker
+[Kuksa Quickstart](quickstart.md) | Introduction on how to interact with Kuksa Databroker
+[Kuksa System Components and Deployment](system-architecture.md) | Description of the Kuksa Architecture
+[Supported Protocols](protocol.md) | Protocols supported by Kuksa Databroker
+[Databroker sdv.databroker.v1 Query Syntax](QUERY.md) | Query syntax available in `sdv.databroker.v1`
+[Kuksa TLS concept](tls.md) | Introduction to the Kuksa TLS Concept
+[Kuksa Authorization Concept](authorization.md) | Introduction to the Kuksa Token Concept
+[Runtime behavior and potential attacks](behavior.md) | Description of the runtime behavior of Kuksa Databroker
+[Deployment Blueprints](deployment.md) | Logical description of possible deployments of Kuksa
+[Kuksa Analysis](kuksa_analysis.md) |Functional requirements, design topics and use case diagrams
+[Mapping VSS data types to protobuf Types](TYPES.md) | How VSS datatypes are represented internally in Kuksa Databroker
+[Terminology](terminology.md) | Description of terms commonly used in Kuksa Documentation
+[Wildcard Matching Rules](wildcard_matching.md) | Wildcard matching rules for `sdv.databroker.v1` and `kuksa.val.v1`

doc/TYPES.md

@@ -1,4 +1,4 @@
-# Mapping data types
+# Mapping VSS data types to Protobuf Types
 
 This is how [VSS data types](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_types/)
 defined by [COVESA VSS](https://covesa.github.io/vehicle_signal_specification/) are mapped to the data types used by
@@ -37,4 +37,4 @@ See `enum DataType` in [types.proto](../proto/kuksa/val/v1/types.proto) for the
 | uint64[]      | UINT64_ARRAY              |                     - |
 | float[]       | FLOAT_ARRAY               |                     - |
 | double[]      | DOUBLE_ARRAY              |                     - |
-| timestamp[]   | TIMESTAMP_ARRAY           |                     - |
+| timestamp[]   | TIMESTAMP_ARRAY           |                     - |

doc/authorization.md

@@ -1,4 +1,4 @@
-# Authorization in KUKSA.VAL
+# Kuksa Authorization Concept
 
 * [Background](#background)
 * [Introduction to OAuth2](#introduction)
@@ -64,7 +64,7 @@ orientation around how it fits into the overall OAuth 2.0 Authorization Framewor
 # Introduction to OAuth2
 Using an authorization framework like OAuth2 is well suited for an environment where third party
 applications need delegated access to a resource, while at the same time restricting the scope
-of this access to minimum. 
+of this access to minimum.
 
 See [The OAuth 2.0 Authorization Framework](#the-oauth-20-authorization-framework) for a more
 detailed description of the benefits, and the problems the framework aims to solve.
@@ -75,7 +75,7 @@ OAuth 2.0 defines four roles:
   >   An entity capable of granting access to a protected resource.
   >   When the resource owner is a person, it is referred to as an
   >   end-user.
-  
+
   The resource owner in this context could be the OEM or the owner of a vehicle.
 
 * **Resource server**
@@ -421,19 +421,19 @@ Example:
 > * Third-party applications are required to store the resource
 >   owner's credentials for future use, typically a password in
 >   clear-text.
-> 
+>
 > * Servers are required to support password authentication, despite
 >   the security weaknesses inherent in passwords.
-> 
+>
 > * Third-party applications gain overly broad access to the resource
 >   owner's protected resources, leaving resource owners without any
 >   ability to restrict duration or access to a limited subset of
 >   resources.
-> 
+>
 > * Resource owners cannot revoke access to an individual third party
 >   without revoking access to all third parties, and must do so by
 >   changing the third party's password.
-> 
+>
 > * Compromise of any third-party application results in compromise of
 >   the end-user's password and all of the data protected by that
 >   password.
@@ -462,47 +462,47 @@ Example:
 > represent specific scopes and durations of access, granted by the
 > resource owner, and enforced by the resource server and authorization
 > server.
-> 
+>
 > The token may denote an identifier used to retrieve the authorization
 > information or may self-contain the authorization information in a
 > verifiable manner (i.e., a token string consisting of some data and a
 > signature).  Additional authentication credentials, which are beyond
 > the scope of this specification, may be required in order for the
 > client to use a token.
-> 
+>
 > The access token provides an abstraction layer, replacing different
 > authorization constructs (e.g., username and password) with a single
 > token understood by the resource server.  This abstraction enables
 > issuing access tokens more restrictive than the authorization grant
 > used to obtain them, as well as removing the resource server's need
 > to understand a wide range of authentication methods.
-   
+
 [[RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-1.4)]
 
 #### Roles
 > OAuth defines four roles:
-> 
+>
 > * **resource owner**
->   
+>
 >   An entity capable of granting access to a protected resource.
 >   When the resource owner is a person, it is referred to as an
 >   end-user.
-> 
+>
 > * **resource server**
->   
+>
 >   The server hosting the protected resources, capable of accepting
 >   and responding to protected resource requests using access tokens.
-> 
+>
 > * **client**
->   
+>
 >   An application making protected resource requests on behalf of the
 >   resource owner and with its authorization.  The term "client" does
 >   not imply any particular implementation characteristics (e.g.,
 >   whether the application executes on a server, a desktop, or other
 >   devices).
-> 
+>
 > * **authorization server**
->   
+>
 >   The server issuing access tokens to the client after successfully
 >   authenticating the resource owner and obtaining authorization.
 
@@ -515,13 +515,13 @@ Example:
 > This specification defines a profile for issuing OAuth 2.0 access tokens in JSON Web Token (JWT)
   format. Authorization servers and resource servers from different vendors can leverage this
   profile to issue and consume access tokens in an interoperable manner.
-> 
+>
 > The original OAuth 2.0 Authorization Framework [RFC6749] specification does not mandate any
   specific format for access tokens. While that remains perfectly appropriate for many important
   scenarios, in-market use has shown that many commercial OAuth 2.0 implementations elected to
   issue access tokens using a format that can be parsed and validated by resource servers directly,
   without further authorization server involvement.
-> 
+>
 > This specification aims to provide a standardized and interoperable profile as an alternative to
   the proprietary JWT access token layouts going forward. Besides defining a common set of
   mandatory and optional claims, the profile provides clear indications on how authorization
@@ -557,4 +557,3 @@ Example:
 * [The OAuth 2.0 Authorization Framework [RFC 6749]](https://www.rfc-editor.org/rfc/rfc6749)
 
 * [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens [RFC 9068]](https://datatracker.ietf.org/doc/html/rfc9068)
-