feat(wip): add search and on_search channels to api

[gamemaker1]

Description

This PR adds the search and on_search channels to the asynchronous API.

Architecture

Here is a very basic architecture diagram for making a search request using a pub-sub architecture:

sequenceDiagram
    participant BA as Beckn Application
    participant BG as Beckn Gateway (Message Broker)
    participant BP as Beckn Provider
    BA ->> BG: BA publishes request to `search` channel
    BG ->> BP: BG propagates `search` request to BPs
    BP ->> BG: Each BP publishes its response to the `on_search` channel
    BG ->> BA: BG propagates `on_search` responses to the BA

Loading

This architecture assumes the following:

• the Beckn Gateway can act as the message broker and ensure messages are sent and received by the right entities
• the Beckn Application and Beckn Providers have already subscribed to the search channel while registering (Maybe registration can be done via a REST API call to the Beckn Gateway?)

For a search request, here is the flow of events:

• The Beckn Application publishes a message (the 'request') to the search channel.
• The Beckn Providers that are subscribed to the channel receive the message.
• Each Beckn Provider checks if they can fulfill the intent specified in the request, they publish a message (the 'response') in the on_search channel.
• The Beckn Application is subscribed to the on_search channel and receives responses from each Beckn Provider asynchronously.

Schemas

All messages sent in any channel will be sent in the following 'envelope':

{
	"meta": {
		"signature": {
			"hash": "string",
			"digest": "string",
			"algorithm": "ed25519"
		}
	},
	"data": {
		"context": {
			"...": "..."
		},
		"message": {
			"...": "..."
		}
	}
}

The meta field is the request metadata, equivalent to the headers of an HTTP request. The data field is the Beckn request data, equivalent to the body of an HTTP request.

The signature field (for now) simply includes the hex-encoded hash of the data object as JSON with no newlines/spaces/indentation. This field should then be signed by the message publisher's private key, and the digital signature thus created can be placed in the digest field.

The context field contains information about the request/response and entity making the request/response. The message field differs based on the operation being performed (search, init, confirm, etc.)

---

@Vedsaga @venkatramanm please review and let me know what could be improved!

[Vedsaga]

This looks good to me; but I have few fundamental question.

So, I believe the idea here is to create fundamental protocol which can be adhere by all the event-borker (topic managers of the event).
And, each broker will have it's independent db workings.

Now, existing data-structure is like this

     "context": {
			"...": "..."
		},
		"message": {
			"...": "..."
		}

So, instead of warping the packet with the meta could we not put meta inside the context because context is read by the BG to forward the packet to right entity. Here I am assuming that pub-sub event-borker will act as entity who will receive and response to the message.

So, if we are making the meta then doesn't it mean that we have to change the existing protocol structure of beckn?

[gamemaker1]

Currently, the Beckn Protocol specification is a little HTTP-oriented. Several fields, like the signature, are sent as HTTP headers according to the OpenAPI definition of the protocol.

To ensure the pub sub spec also has these features, I created a little 'envelope' that has two parts - a meta field that acts as the HTTP headers, and the data field that acts like the request body. Anything that belongs in the request body according to the OpenAPI definition should go in the data field, and the properties of the meta field can be decided by us (just like the headers to use are decided by the HTTP implementation), as it is pub-sub specific. In the long term, this will enable us to add pub-sub specific fields like status, ttl, etc as you have proposed here - beckn/protocol-specifications#189 (comment).

[Vedsaga]

I agree with that approach. However one query which isn't all the packet which origin from BAP or BPPs are already HTTP-oriented that mean they already have define specification such ttl & signature. So, are we again here warping those packet with new HTTP specification . I was thinking that we can leverage existing HTTP specs and just create another meta{} inside the context.

[gamemaker1]

However one query which isn't all the packet which origin from BAP or BPPs are already HTTP-oriented that mean they already have define specification such ttl & signature. So, are we again here warping those packet with new HTTP specification

I didn't understand what you meant to say, could you please elaborate? Edit: I think you mean that we are duplicating the fields that are already in context, but we will only add fields that cannot already be derived from fields in the context object. One example is signature, which is not included in the context object but in the request headers in the OpenAPI spec only.

Just create another meta{} inside the context

I think we should try to keep the Core APIs and schemas the same. Adding meta inside the context field will mean changing the schema.

[gamemaker1]

Basically in the HTTP implementation, the Beckn request is inside the request body, while in the Pub-Sub implementation, the Beckn request is inside the data field.

HTTP-specific things like Accept, Content-Type, Connection and Authorization are passed in the request headers, while here they will be passed in the meta field.

[venkatramanm]

Btw gateways don't read context. They only read headers.

[gamemaker1]

Hi,

I have just added the minimum set of schemas to the spec for the search and on_search channels (mostly copied over from https://github.com/beckn/protocol-specifications/blob/master/core/v0/api/core.yaml), I will improve the descriptions for the schemas, add more comments and then request a final review.

You could view a simulation and documentation of the spec here.