updated readme, added interface to plugin, updated example

Author: Semior001

README.md

@@ -14,19 +14,21 @@ Help Options:
 [run command options]
       -c, --config_location=    location of the configuration file
                                 [$CONFIG_LOCATION]
+          --update_timeout=     amount of time per processing single update
+                                [$UPDATE_TIMEOUT]
 
-store:
-      --store.type=[bolt]   type of storage [$STORE_TYPE]
+    store:
+          --store.type=[bolt]   type of storage [$STORE_TYPE]
 
-bolt:
-      --store.bolt.path=    parent dir for bolt files (default: ./var)
-                            [$STORE_BOLT_PATH]
-      --store.bolt.timeout= bolt timeout (default: 30s)
-                            [$STORE_BOLT_TIMEOUT]
+    bolt:
+          --store.bolt.path=    parent dir for bolt files (default: ./var)
+                                [$STORE_BOLT_PATH]
+          --store.bolt.timeout= bolt timeout (default: 30s)
+                                [$STORE_BOLT_TIMEOUT]
 
-webhook:
-      --webhook.base_url=   base url for webhooks [$WEBHOOK_BASE_URL]
-      --webhook.addr=       local address to listen [$WEBHOOK_ADDR]
+    webhook:
+          --webhook.base_url=   base url for webhooks [$WEBHOOK_BASE_URL]
+          --webhook.addr=       local address to listen [$WEBHOOK_ADDR]
 ```
 
 ### DSL
@@ -40,24 +42,33 @@ trackers:
     with:
       owner: cappuccinotm
       name: dastracker
-      user: "{{ env \"GITHUB_USER\" }}"
-      access_token: "{{ env \"GITHUB_ACCESS_TOKEN\" }}"
+      user: '{{ env "GITHUB_USER" }}'
+      access_token: '{{ env "GITHUB_ACCESS_TOKEN" }}'
 
   - name: customrpc
     driver: rpc
     with:
-      address: "{{ env \"CUSTOM_RPC_ADDRESS\" }}"
+      address: '{{ env "CUSTOM_RPC_ADDRESS" }}'
+
+triggers:
+  - name: gh_task_updated
+    in: gh_dastracker
+    with:
+      events: "issues"
 
 jobs:
   - name: print task update if task is received
-    on:
-      tracker: gh_dastracker
-      with:
-        events: "issue"
+    on: gh_task_updated
     do:
-      - action: customrpc/Print
-        with:
-          message: "Task \"{{.Update.Title}}\" has been updated and printed to the terminal."
+      - if: 'string_contains(Update.Title, "[PTT]")' # means "Print To Terminal"
+        do:
+          - action: customrpc/Print
+            detached: true
+            with:
+              message: |
+                Task "{{.Update.Title}}" has been updated and printed to the terminal. 
+                Body: 
+                {{.Update.Body}}
 ```
 
 This flow checks whether any issue in github is updated and sends an RPC call to Print method with the
@@ -69,35 +80,37 @@ The configuration file uses the [go template language](https://pkg.go.dev/text/t
 
 Helper methods:
 
-| Method name                       | Description                                                  |
-|-----------------------------------|--------------------------------------------------------------|
-| env(varname string)               | returns the value of the environment variable                |
-| values(m map[string]string)       | returns a list of values of the map                          |
-| seq(l []string)                   | serializes the list in form of "string1,string2,string3,..." |
+| Method name                              | Description                                                  |
+|------------------------------------------|--------------------------------------------------------------|
+| env(varname string)                      | returns the value of the environment variable                |
+| values(m map[string]string)              | returns a list of values of the map                          |
+| seq(l []string)                          | serializes the list in form of "string1,string2,string3,..." |
+| string_contains(s string, substr string) | returns true if string contains substring                    |
 
 ### TODO
 - [X] RPC plugins support
-- [ ] Github support
-- [ ] Predicates for triggers
-- [ ] Asana support
-- [ ] Jira support
-- [ ] Increase test coverage
-- [ ] Update history
+- [ ] Github support (partially)
+- [X] Predicates for triggers
 - [ ] Special mappings
 - [ ] Detached actions
 
 ### Terminology
-We use a word "ticket" for a task in the context of "dastracker" and the word "task" 
-in the context of the external task trackers.
+- Ticket - an issue in the context of "dastracker"
+- Task - an issue in the context of the end task tracker.
+- Subscription - a webhook or polling, for retrieving updates from the end task tracker.
 
 ### Plugin development
 The functionality of dastracker might be extended by using plugins. Each plugin is an independent process/container, 
 implementing [Go RPC server](https://pkg.go.dev/net/rpc). Each exported method of the plugin handler must have a signature of `func(req lib.Request, res *lib.Response)`, 
 these methods might be referred and called in the configuration.
 
-Also, the `lib.Plugin` structure has a field, named `SetUpTrigger` with signature of `func(req SetUpTriggerReq, resp *SetUpTriggerResp) error`. 
-This field might be filled in order to allow hanging on some triggers in the configuration file. 
-If no method is provided, dastracker will do nothing on any trigger, hanged on the plugin.
+Plugin may provide methods to subscribe and unsubscribe from events, for that, plugin should implement interface:
+```go
+type SubscriptionSupporter interface {
+	Subscribe(req SubscribeReq, resp *SubscribeResp) error
+	Unsubscribe(req UnsubscribeReq, _ *struct{}) error
+}
+```
 
 See [example](_example/plugin/main.go) for details. 
 
@@ -128,13 +141,3 @@ Some details about JSONRPC:
       "id": 0
     }
     ```
-**(TODO)**
-
-Demo: 
-![](docs/demo.gif)
-
-### Requirements
-Read about requirements in [here](docs/REQUIREMENTS.md)
-
-### Design
-Read about design in [here](docs/DESIGN.md)

_example/plugin/main.go

@@ -9,7 +9,17 @@ import (
 
 type Handler struct{}
 
-func (h *Handler) Print(req lib.Request, _ *lib.Response) error {
+func (Handler) Subscribe(req lib.SubscribeReq, _ *lib.SubscribeResp) error {
+	log.Printf("Subscribe called: %+v", req)
+	return nil
+}
+
+func (Handler) Unsubscribe(req lib.UnsubscribeReq, _ *struct{}) error {
+	log.Printf("Unsubscribe called: %+v", req)
+	return nil
+}
+
+func (Handler) Print(req lib.Request, _ *lib.Response) error {
 	msg := req.Vars.Get("message")
 	log.Printf("Received Print call with msg: %s", msg)
 	return nil
@@ -18,16 +28,9 @@ func (h *Handler) Print(req lib.Request, _ *lib.Response) error {
 func main() {
 	pl := lib.Plugin{
 		Address: ":9000",
-		SubscribeHandler: func(req lib.SubscribeReq) error {
-			log.Printf("[INFO] requested subscription with webhook on %s", req.WebhookURL())
-			return nil
-		},
-		UnsubscribeHandler: func(req lib.UnsubscribeReq) error {
-			log.Printf("[INFO] requested unsubscription")
-			return nil
-		},
+		Logger:  log.Default(),
 	}
-	if err := pl.Listen(context.Background(), &Handler{}); err != nil {
+	if err := pl.Listen(context.Background(), Handler{}); err != nil {
 		log.Printf("[WARN] listener stopped, reason: %v", err)
 	}
 }

_example/plugin/vendor/github.com/cappuccinotm/dastracker/lib/plugin.go

@@ -1,8 +1,3 @@
-# provided functions:
-# env "NAME" - returns the value of environment variable NAME
-# values <map> - returns a list of values of the map
-# seq <list[string]> - serializes the list in form of "string1,string2,string3,..."
-
 trackers:
   - name: gh_dastracker
     driver: github
@@ -22,6 +17,10 @@ triggers:
     in: gh_dastracker
     with:
       events: "issues"
+  - name: test_customrpc_subscribe
+    in: customrpc
+    with:
+      events: "subscribe"
 
 jobs:
   - name: print task update if task is received

_example/plugin/vendor/github.com/cappuccinotm/dastracker/lib/rpc.go

@@ -194,6 +194,9 @@ func (s *Actor) registerTriggers(ctx context.Context) error {
 				return fmt.Errorf("set tracker reference %q in subscription %q: %w", resp.TrackerRef, sub.ID, err)
 			}
 
+			s.Log.Printf("[DEBUG] registered subscription %q in %q, received tracker reference: %q",
+				trigger.Name, trigger.Tracker, resp.TrackerRef)
+
 			return nil
 		})
 	}
@@ -230,6 +233,9 @@ func (s *Actor) unregisterTriggers(ctx context.Context) {
 			if err = s.SubscriptionsManager.Delete(ctx, sub.ID); err != nil {
 				s.Log.Printf("[WARN] failed to delete subscription %q: %v", sub.ID, err)
 			}
+
+			s.Log.Printf("[DEBUG] unregistered subscription with id %q, trigger %q in %q, with tracker reference: %q",
+				sub.ID, sub.TriggerName, sub.TrackerName, sub.TrackerRef)
 		}()
 	}