[PREALPHA] Camino Messenger Protocol definition (#1)

Pre-alpha state of the CMP definition.

---------

Co-authored-by: Sam Jaarsma <[email protected]>

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+* @havan
+* @SamJaarsma

.github/workflows/ci.yaml

@@ -0,0 +1,108 @@
+name: CI
+
+on:
+  push:
+    # Only run when there are changes under proto dir
+    paths:
+      - "proto/**"
+      - ".github/workflows/**"
+  pull_request:
+    # Only run when there are changes under proto dir
+    paths:
+      - "proto/**"
+      - ".github/workflows/**"
+
+jobs:
+  # Run buf's lint to check for errros
+  buf-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+      - name: Install buf
+        run: |
+          # Installing buf
+          if [ "${{ env.buf_version }}" == "" ]; then
+            # Install latest version
+            sudo ./scripts/buf-installer.sh
+          else
+            # Install the defined version
+            sudo ./scripts/buf-installer.sh --version=${{ env.buf_version}}
+          fi
+      - name: Buf lint
+        uses: bufbuild/buf-lint-action@v1
+        with:
+          input: "proto"
+  # Push the draft branch to buf.build
+  bsr-push-draft:
+    runs-on: ubuntu-latest
+    needs: buf-lint
+    if: github.ref == 'refs/heads/draft'
+    environment: draft
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+      - name: Install Buf
+        run: |
+          # Install Buf
+          if [ "${{ env.buf_version }}" == "" ]; then
+            # Install latest version
+            sudo ./scripts/buf-installer.sh
+          else
+            # Install the defined version
+            sudo ./scripts/buf-installer.sh --version=${{ env.buf_version}}
+          fi
+      - name: Push to buf.build
+        uses: bufbuild/buf-push-action@v1
+        with:
+          input: "proto"
+          draft: true
+          buf_token: ${{ secrets.BUF_BSR_TOKEN }}
+
+  # Generate and upload protodot diagrams
+  diagrams:
+    runs-on: ubuntu-latest
+    needs: buf-lint
+    if: github.ref == 'refs/heads/draft'
+    steps:
+      # Setup environment
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v1
+      - name: Install librsvg2-bin
+        run: sudo apt-get install -y librsvg2-bin
+
+      # Generate diagrams
+      - name: Generate Diagrams
+        run: |
+          # Install protodot
+          wget https://github.com/seamia/protodot/raw/master/binaries/protodot-linux-amd64
+          chmod +x protodot-linux-amd64
+          mkdir -v -p gen/bin
+          mv protodot-linux-amd64 gen/bin/protodot
+          export PATH=${PWD}/gen/bin:${PATH}
+
+          # Run generator script
+          bash scripts/generate_protodot.sh
+
+          # Remove .dot files, we do not need them.
+          find gen/diagrams -type f -name "*.dot" -exec rm -f {} +
+
+          # Show generated files
+          tree gen/diagrams
+
+      # Upload diagrams
+      - name: Cloud Authentication
+        id: auth
+        uses: "google-github-actions/auth@v1"
+        with:
+          credentials_json: "${{ secrets.GOOGLE_CREDENTIALS }}"
+
+      - name: Setup Cloud SDK
+        uses: google-github-actions/setup-gcloud@v1
+
+      - name: Upload Diagrams
+        run: |
+          # '-J' options is to set Content-Encoding to gzip
+          gsutil -m rsync -J -R -d gen/diagrams gs://docs-cmp-files/diagrams

.gitignore

@@ -0,0 +1,3 @@
+gen
+.vscode
+

Makefile

@@ -0,0 +1,37 @@
+# Generation Settings
+GENERATED_DIR = gen
+MODULLE_DIR = proto/cmp
+PROTOC = protoc
+
+# Protodot diagrams
+PROTODOT = protodot
+PROTODOT_DIR = diagrams
+
+# Colors
+GREEN=\033[92m
+BLUE=\033[94m
+RESET=\033[0m
+
+# Default target
+all: diagrams
+
+# Generate protodot diagrams
+diagrams: ${GENERATED_DIR}/${PROTODOT_DIR}
+	@echo "${GREEN}Generating Protodot Diagrams files${RESET}"
+	./scripts/generate_protodot.sh ${GENERATED_DIR} ${MODULLE_DIR} ${PROTODOT_DIR}
+
+# Create necessary directories if they do not exist
+${GENERATED_DIR}/${PROTODOT_DIR}:
+	mkdir -p $@
+
+clean:
+	rm -rfv ${GENERATED_DIR}/*
+
+sabledocs:
+	protoc proto/cmp/*/*.proto -o descriptor.pb --include_source_info
+	sabledocs
+	mv sabledocs_output ${GENERATED_DIR}/
+	rm -fv descriptor.pb
+
+# Mark commands as phony so make knows they're not associated with files
+.PHONY: all clean diagrams sabledocs

buf.gen.yaml

@@ -12,3 +12,5 @@ plugins:
     opt: paths=source_relative
   - plugin: buf.build/community/danielgtaylor-betterproto:v1.2.5
     out: gen/python
+  - plugin: buf.build/protocolbuffers/python:v25.1
+    out: gen/pbpy

proto/cmp/services/accommodation/v1alpha1/list.proto

@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+package cmp.services.accommodation.v1alpha1;
+
+import "cmp/services/accommodation/v1alpha1/property_types.proto";
+import "cmp/types/v1alpha1/common.proto";
+import "google/protobuf/timestamp.proto";
+
+message AccommodationProductListRequest {
+  // Message header
+  cmp.types.v1alpha1.Header header = 1;
+
+  // Only respond with the products that are modified after this timestamp
+  google.protobuf.Timestamp modified_after = 2;
+}
+
+message AccommodationProductListResponse {
+  // Message header
+  cmp.types.v1alpha1.Header header = 1;
+
+  // Product list: Properties
+  repeated Property properties = 2;
+}
+
+// ### Accommodation Product List Service
+//
+// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha1/list.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha1/list.proto.dot.svg)
+service AccommodationProductListService {
+  // Returns product list for accommodation (properties)
+  rpc AccommodationProductList(AccommodationProductListRequest) returns (AccommodationProductListResponse);
+}

proto/cmp/services/accommodation/v1alpha1/property_types.proto

@@ -0,0 +1,94 @@
+syntax = "proto3";
+
+package cmp.services.accommodation.v1alpha1;
+
+import "cmp/types/v1alpha1/address.proto";
+import "cmp/types/v1alpha1/email.proto";
+import "cmp/types/v1alpha1/location.proto";
+import "cmp/types/v1alpha1/phone.proto";
+import "google/protobuf/timestamp.proto";
+
+// ### Property message type
+//
+// Represents property info for an accommodation product
+//
+// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/accommodation/v1alpha1/property_types.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/accommodation/v1alpha1/property_types.proto.dot.svg)
+message Property {
+  // Ex: "2023-08-28T12:03:50",
+  google.protobuf.Timestamp last_modified = 1;
+
+  // Ex: "AESPMI1234"
+  string property_code = 2;
+
+  // Ex: "Beach Hotel Alanya"
+  string name = 3;
+
+  // Ex: "Hilton"
+  string chain = 4;
+
+  // Ex: CategoryRating.CATEGORY_RATING_4_5
+  CategoryRating category_rating = 5;
+
+  // Ex: CategoryUnit.CATEGORY_UNIT_PALMS
+  CategoryUnit category_unit = 6;
+
+  // Ex: Address type
+  cmp.types.v1alpha1.Address address = 7;
+
+  // Emails
+  repeated cmp.types.v1alpha1.Email emails = 8;
+
+  // Phones
+  repeated cmp.types.v1alpha1.Phone phones = 9;
+
+  // Location coordinate
+  cmp.types.v1alpha1.Coordinate coordinate = 10;
+
+  // Ex: "www.hotel.com"
+  string website = 11;
+
+  // Status of the property
+  // FIXME: Changed "deactivated" to "status". But we should still make this an enum. ??
+  string status = 12;
+
+  // GIATA ID
+  string giata_id = 13;
+
+  // Goal ID
+  int32 goal_id = 14;
+
+  // Airports
+  // Ex: ["PMI", "ZRH", "AYT"]
+  repeated string airports = 15;
+}
+
+enum CategoryRating {
+  CATEGORY_RATING_UNSPECIFIED = 0;
+  CATEGORY_RATING_0_5 = 1;
+  CATEGORY_RATING_1_0 = 2;
+  CATEGORY_RATING_1_5 = 3;
+  CATEGORY_RATING_2_0 = 4;
+  CATEGORY_RATING_2_5 = 5;
+  CATEGORY_RATING_3_0 = 6;
+  CATEGORY_RATING_3_5 = 7;
+  CATEGORY_RATING_4_0 = 8;
+  CATEGORY_RATING_4_5 = 9;
+  CATEGORY_RATING_5_0 = 10;
+  CATEGORY_RATING_5_5 = 11;
+  CATEGORY_RATING_6_0 = 12;
+  CATEGORY_RATING_6_5 = 13;
+  CATEGORY_RATING_7_0 = 14;
+  CATEGORY_RATING_7_5 = 15;
+  CATEGORY_RATING_8_0 = 16;
+  CATEGORY_RATING_8_5 = 17;
+  CATEGORY_RATING_9_0 = 18;
+  CATEGORY_RATING_9_5 = 19;
+  CATEGORY_RATING_10_0 = 20;
+}
+
+enum CategoryUnit {
+  CATEGORY_UNIT_UNSPECIFIED = 0;
+  CATEGORY_UNIT_STARS = 1;
+  CATEGORY_UNIT_PALMS = 2;
+}

proto/cmp/services/accommodation/v1alpha1/search.proto

@@ -0,0 +1,91 @@
+syntax = "proto3";
+
+// ## Accommodation Services
+//
+// The Accommodation services are used for both hotels and holiday homes, often
+// called short term rentals.
+//
+// Any search message response in the Camino Messenger Protocol only includes
+// dynamic data. Static data can be cached and kept up to data with the Product List
+// and Product Details messages.
+//
+// This package is a **WIP**.
+package cmp.services.accommodation.v1alpha1;
+
+import "cmp/services/accommodation/v1alpha1/search_parameters_types.proto";
+import "cmp/services/accommodation/v1alpha1/search_result_types.proto";
+import "cmp/services/accommodation/v1alpha1/unit_types.proto";
+import "cmp/types/v1alpha1/common.proto";
+import "cmp/types/v1alpha1/search.proto";
+import "cmp/types/v1alpha1/travel_period.proto";
+import "cmp/types/v1alpha1/traveller.proto";
+
+// ### Accommodation Search Request Message Type
+//
+// The `Accommodation Search Request` message type facilitates the request for
+// accommodations like hotel and holiday home searches within the platform. In the
+// request the market, language and currency are specified at the top-level. In the
+// Unit we specify the details of the trip like dates, properties or locations or
+// filters. The purpose of such a structure is to allow for multi-room and
+// multi-property searches, so that several rooms or houses can be requested for the
+// same dates and location or for the purpose of a tour or roadtrip, several
+// accommodations for sequential dates and different locations.
+//
+// Developers leveraging this message type should ensure proper validation and
+// handling, especially considering fields that are still under review, like
+// `speech_request`.
+message AccommodationSearchRequest {
+  // Message header. Contains API version, message info string and end-user wallet
+  // address
+  cmp.types.v1alpha1.Header header = 1;
+
+  // Search request metadata
+  cmp.types.v1alpha1.SearchRequestMetadata metadata = 2;
+
+  // Generic search parameters Ex: Inclusion of OnRequest options and inclusion of
+  // only the cheapest or all options.
+  cmp.types.v1alpha1.SearchParameters search_parameters_generic = 3;
+
+  // Accommodation specific search parameters Ex: Specific search parameters like
+  // geo location, meal plan, rate plan and rate rules.
+  AccommodationSearchParameters search_parameters_accommodation = 4;
+
+  // Travel period
+  cmp.types.v1alpha1.TravelPeriod travel_period = 5;
+
+  // Travellers
+  repeated cmp.types.v1alpha1.Traveller travellers = 6;
+
+  // Unit Types
+  repeated UnitType unit_types = 7;
+}
+
+// ### Accommodation Search Response
+//
+// The `Accommodation Search Response` message type facilitates the response for
+// accommodations like hotel and holiday home searches within the platform.
+//
+// In the response a search_id must be included and a search_option_id for every
+// bookable option responded. Included, compulsary and optional services can be
+// included. A simple "free cancellation upto" can be set or full cancellation
+// pilicies can be included.
+message AccommodationSearchResponse {
+  // Message header. Contains API version, message info string and end user wallet
+  // address.
+  cmp.types.v1alpha1.Header header = 1;
+
+  // Search response metadata
+  cmp.types.v1alpha1.SearchResponseMetadata metadata = 2;
+
+  // Unique combinations of bookable search results, like property,
+  repeated AccommodationSearchResult results = 3;
+}
+
+// ### Accommodation Search Service definition
+//
+// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/accommodation/v1alpha1/search.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/accommodation/v1alpha1/search.proto.dot.svg)
+service AccommodationSearchService {
+  // Accommodation Search method
+  rpc AccommodationSearch(AccommodationSearchRequest) returns (AccommodationSearchResponse);
+}