Update API section with WTP definition

Change-Id: I611602ad52df6b954fda2b3217534472c2270cb2
Issue-ID: DCAEGEN2-858
Signed-off-by: Piotr Jaszczyk <piotr.jaszczyk@nokia.com>

3 files changed, 152 insertions, 0 deletions

diff --git a/docs/sections/apis/ves-hv/VesEvent.proto b/docs/sections/apis/ves-hv/VesEvent.proto
new file mode 100644
index 00000000..dbe0aa3f
--- /dev/null
+++ b/docs/sections/apis/ves-hv/VesEvent.proto
@@ -0,0 +1,76 @@
+/*
+ * ============LICENSE_START=======================================================
+ * dcaegen2-collectors-veshv
+ * ================================================================================
+ * Copyright (C) 2018 NOKIA
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+syntax = "proto3";
+package org.onap.ves;
+
+message VesEvent                            // top-level message, currently the maximum event size supported by the HV-VES Collector is 1 MiB
+{
+    CommonEventHeader commonEventHeader=1;  // required
+
+    bytes eventFields=2;                    // required, payload
+        // this field contains a domain-specific GPB message
+        // the field being opaque (bytes), the decoding of the payload occurs in a separate step
+        // the name of the GPB message for domain XYZ is XyzFields
+        // e.g. for domain==perf3gpp, the GPB message is Perf3gppFields
+}
+
+// VES CommonEventHeader adapted to GPB (Google Protocol Buffers)
+// Aligned with VES 7.0.1 schema, and extending to Performance Domain.
+
+message CommonEventHeader
+{
+    string version = 1;                     // required, "version of the gpb common event header", current value "1.0"
+    string domain = 2;                      // required, "the eventing domain associated with the event", allowed values:
+                                            // fault, heartbeat, measurement, mobileFlow, other, pnfRegistration, sipSignaling,
+                                            // stateChange, syslog, thresholdCrossingAlert, voiceQuality, perf3gpp
+
+    uint32 sequence = 3;                    // required, "ordering of events communicated by an event source instance or 0 if not needed"
+
+    enum Priority
+    {
+        PRIORITY_NOT_PROVIDED = 0;
+        HIGH = 1;
+        MEDIUM = 2;
+        NORMAL = 3;
+        LOW = 4;
+    }
+    Priority priority = 4;                  // required, "processing priority"
+
+    string eventId = 5;                     // required, "event key that is unique to the event source"
+    string eventName = 6;                   // required, "unique event name"
+    string eventType = 7;                   // "for example - guest05,  platform"
+
+    uint64 lastEpochMicrosec = 8;           // required, "the latest unix time aka epoch time associated with the event from any component--as microseconds elapsed since 1 Jan 1970 not including leap seconds"
+    uint64 startEpochMicrosec = 9;          // required, "the earliest unix time aka epoch time associated with the event from any component--as microseconds elapsed since 1 Jan 1970 not including leap seconds"
+
+    string nfNamingCode = 10;               // "4 character network function type, aligned with vnf naming standards"
+    string nfcNamingCode = 11;              // "3 character network function component type, aligned with vfc naming standards"
+    string nfVendorName = 12;               // " Vendor Name providing the nf "
+
+    bytes reportingEntityId = 13;           // "UUID identifying the entity reporting the event, for example an OAM VM; must be populated by the ATT enrichment process"
+    string reportingEntityName = 14;        // required, "name of the entity reporting the event, for example, an EMS name; may be the same as sourceName should match A&AI entry"
+    bytes sourceId = 15;                    // "UUID identifying the entity experiencing the event issue; must be populated by the ATT enrichment process"
+    string sourceName = 16;                 // required, "name of the entity experiencing the event issued use A&AI entry"
+    string timeZoneOffset = 17;             // "Offset to GMT to indicate local time zone for the device"
+    string vesEventListenerVersion = 18;    // required, "Version of the VesEvent Listener", current value "7.0.2"
+
+    reserved "InternalHeaderFields";        // "enrichment fields for internal VES Event Listener service use only, not supplied by event sources"
+    reserved 100;
+}
diff --git a/docs/sections/apis/ves-hv/WTP.asn b/docs/sections/apis/ves-hv/WTP.asn
new file mode 100644
index 00000000..3c0178d4
--- /dev/null
+++ b/docs/sections/apis/ves-hv/WTP.asn
@@ -0,0 +1,17 @@
+-- Wire Transfer Protocol (binary, defined using ASN.1 notation)
+-- Encoding: use "direct encoding" to the number of octets indicated in the comment [n], using network byte order.
+
+WTP DEFINITIONS ::= BEGIN
+
+-- Used to sent data from the data provider
+WtpData ::= SEQUENCE {
+    magic           INTEGER (0..255),           -- [1] always 0xAA
+    versionMajor    INTEGER (0..255),           -- [1] major interface version, forward incompatible with previous major version, current value: 1
+    versionMinor    INTEGER (0..255),           -- [1] minor interface version, forward compatible with previous minor version, current value: 0
+    reserved        OCTET STRING (SIZE (3)),    -- [3] reserved for future use (ignored, but use 0)
+    payloadId       INTEGER (0..65535),         -- [2] payload type: 0x0000=undefined, 0x0001=ONAP VesEvent (protobuf)
+    payloadLength   INTEGER (0..4294967295).    -- [4] payload length in octets
+    payload         OCTET STRING                -- [length as per payloadLength]
+}
+
+END
diff --git a/docs/sections/apis/ves-hv/index.rst b/docs/sections/apis/ves-hv/index.rst
new file mode 100644
index 00000000..799f92d4
--- /dev/null
+++ b/docs/sections/apis/ves-hv/index.rst
@@ -0,0 +1,59 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+========================
+HV-VES (High Volume VES)
+========================
+
+:Date: 2018-10-05
+
+.. contents::
+    :depth: 3
+..
+
+Overview
+========
+
+Component description can be found under `HV-VES Collector`_.
+
+.. _HV-VES Collector: ../../services/ves-hv/index.html
+
+
+TCP Endpoint
+============
+
+HV-VES is exposed as NodePort service on Kubernetes cluster on port 30222/tcp.
+It uses plain TCP connections tunneled in SSL/TLS or can be run in insecure manner without data encryption on the socket.
+Without TLS client authentication/authorization is not possible.
+Connections are stream-based (as opposed to request-based) and long running.
+
+Communication is wrapped with thin Wire Transfer Protocol, which mainly provides delimitation.
+
+.. literalinclude:: WTP.asn
+    :language: asn
+
+Payload is binary-encoded, currently using Google Protocol Buffers representation of the VES Common Header.
+
+.. literalinclude:: VesEvent.proto
+    :language: protobuf
+
+The PROTO file, which contains the VES CommonHeader, comes with a binary-type Payload parameter, where domain-specific
+data shall be placed. Domain-specific data are encoded as well with GPB, and they do require a domain-specific
+PROTO file to decode the data.
+
+HV-VES makes routing decisions based mostly on the content of the **Domain** parameter in VES Common Header.
+
+
+Healthcheck
+===========
+
+Inside HV-VES docker container runs small http service for healthcheck - exact port for this service can be configured
+at deployment using `--health-check-api-port` command line option.
+
+This service exposes single endpoint **GET /health/ready** which returns **HTTP 200 OK** in case HV-VES is healthy
+and ready for connections. Otherwise it returns **HTTP 503 Service Unavailable** with short reason of unhealthiness.
+
+
+
+
+