1. Overview
   
2. Concepts
   
3. Access
   
4. Usage
   
5. Design
   
6. Additional Information
   

Awakari: real-time search results alerting service.

An alert condition represents an event matching criteria. Currently, Awakari supports the following condition types:

• text matching
• numeric comparison (<, ≤, =, ≥, >)
• groups of nested condtions with logic (And, Or, Xor)

Any condition may be negative ("Not"). The matching is structured by design: text and numeric conditions may be used to match a certain attribute of an event.

Subscription is a set of matching conditions associated with a specific user (i.e. alert).

The entity being routed and delivered by Awakari. The accepted format is Cloud Events. There are multiple source integrations, producing events from:

• Web feeds (like RSS)
• Fediverse publishers
• Telegram channels

Using the Awakari cloud API requires mutual TLS authentication and encryption to secure all client data. Hence, to access the cloud API it's necessary to have a client certificate.

Prepare own client certificate request:

openssl req -new -newkey rsa:4096 -nodes \
  -keyout client.key \
  -out client.csr \
  -addext "subjectAltName=DNS:api.awakari.com" \
  -subj '/CN=group0.company1.com'

Warning Never specify additional certificate attributes like "O", "OU", etc. The resulting DN should not contain commas.

Then request the client certificate (currently by email).

Refer to Client SDK Usage.

Preparation steps:

1. Install grpcurl
2. Download the necessary proto files and save to the current directory:
   1. Cloud Events
   2. Reader
   3. Resolver

Usage limit represents the successful API call count limit. The limit is identified per:

• group id
• user id (optional)
• subject

There are the group-level limits where user id is not specified. All users from the group share the group limit in this case.

Usage subject may be one of:

• Subscriptions (code 1)
• Publish Events (code 2)

Check current subscriptions limits ("subj": 1):

grpcurl \
  -key test0.client0.key \
  -cert test0.client0.crt \
  -cacert ca.crt \
  -H 'X-Awakari-User-Id: john.doe@company1.com' \
  -d '{"subj": 1}' \
  api.awakari.com:443 \
  awakari.api.limits.Service/Get

A successfull response looks like:

{
  "count": "1000"
}

Usage permits represents the current usage statistics (counters) by the subject. Similar to usage limit, the counters represent the group-level usage when the user id is empty.

User-specific events publishing permits checking command example:

grpcurl \
  -key test0.client0.key \
  -cert test0.client0.crt \
  -cacert ca.crt \
  -H 'X-Awakari-User-Id: john.doe@company1.com' \
  -d '{"subj": 2}' \
  api.awakari.com:443 \
  awakari.api.permits.Service/GetUsage

Create:

grpcurl \
  -key test0.client0.key \
  -cert test0.client0.crt \
  -cacert ca.crt \
  -H 'X-Awakari-User-Id: john.doe@company1.com' \
  -d @ \
  api.awakari.com:443 \
  awakari.subscriptions.proxy.Service/Create

Example payload:

{
   "description": "Tesla model S updates",
   "enabled": true,
   "cond": {
      "not": false,
      "tc": {
        "key": "",
        "term": "Tesla Model S",
        "exact": false
      }
    }
}

A successful response contains the created subscription id:

{
  "id": "547857e3-adfc-48a5-a49e-110cfdedbaab"
}

Note the created subscription id and use it further to read the events. Learn more about the Subscriptions API.

grpcurl \
  -key test0.client0.key \
  -cert test0.client0.crt \
  -cacert ca.crt \
  -proto reader.proto \
  -max-time 86400 \
  -H 'X-Awakari-User-Id: john.doe@company1.com' \
  -d @ \
  api.awakari.com:443 \
  awakari.reader.Service/Read

Specify the subscription id in the payload:

{"start": {"batchSize": 1, "subId": "547857e3-adfc-48a5-a49e-110cfdedbaab"}}

This starts a reader stream. A new event appear in the response once system receives anything matching the subscription. Leave this shell/window open and switch to another. Later switch back and check for new events received.

It's necessary to acknowledge every received event:

{"ack": { "count": 1}}

grpcurl \
  -key test0.client0.key \
  -cert test0.client0.crt \
  -cacert ca.crt \
  -proto writer.proto \
  -H 'X-Awakari-User-Id: john.doe@company1.com' \
  -d @ \
  api.awakari.com:443 \
  awakari.resolver.Service/SubmitMessages

Specify the events to write in the payload:

{
   "msgs": [
      {
         "id": "3426d090-1b8a-4a09-ac9c-41f2de24d5ac",
         "type": "example.type",
         "source": "example/uri",
         "spec_version": "1.0",
         "attributes": {
            "subject": {
               "ce_string": "Tesla price updates"
            },
            "time": {
               "ce_timestamp": "2023-07-03T23:20:50.52Z"
            }
         },
         "text_data": "Tesla model S is now available at lower price"
      }
   ]
}

A successful response looks like:

{
  "ackCount": 1
}

After this it's possible to submit more events.

When finished, close the writer stream by pressing ^C or leave it open to publish any other events later.

• Roadmap
• Contributing