Add docs on publishing messages in transactions with help of Forwarde…

…r component (#261)

_examples/real-world-examples/transactional-events-forwarder/.validate_example.yml

@@ -0,0 +1,4 @@
+validation_cmd: "docker-compose up"
+teardown_cmd: "docker-compose down"
+timeout: 60
+expected_output: "Sending a prize to the winner"

_examples/real-world-examples/transactional-events-forwarder/README.md

@@ -0,0 +1,21 @@
+# Publishing events in transactions with help of Forwarder component (MySQL to Google Pub/Sub)  
+
+While working with an event-driven application, you may in some point need to store an application state and publish a message
+telling the rest of the system about what just happened. As it may look trivial at a first glance, it could become
+a bit tricky if we consider what can go wrong in case we won't pay enough attention to details.
+
+## Solution
+
+This example presents a solution to this problem: saving events in transaction along with persisting application state. 
+It also compares two other approaches which lack transactional publishing therefore expose application to a risk 
+of inconsistency across the system. 
+
+## Requirements
+
+To run this example you will need Docker and docker-compose installed. See installation guide at https://docs.docker.com/compose/install/
+
+## Running
+
+```bash
+docker-compose up
+```

_examples/real-world-examples/transactional-events-forwarder/docker-compose.yml

@@ -0,0 +1,34 @@
+version: '3'
+services:
+  server:
+    image: golang:1.17
+    environment:
+      - PUBSUB_EMULATOR_HOST=googlecloud:8085
+    depends_on:
+      - mysql
+      - googlecloud
+    volumes:
+      - .:/app
+      - $GOPATH/pkg/mod:/go/pkg/mod
+    working_dir: /app
+    command: go run .
+
+  mysql:
+    image: mysql:8.0
+    restart: unless-stopped
+    logging:
+      driver: none
+    ports:
+      - 3306:3306
+    environment:
+      MYSQL_DATABASE: watermill
+      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
+
+  googlecloud:
+    image: google/cloud-sdk:360.0.0
+    logging:
+      driver: none
+    entrypoint: gcloud --quiet beta emulators pubsub start --host-port=0.0.0.0:8085 --verbosity=debug --log-http
+    ports:
+      - 8085:8085
+    restart: unless-stopped

_examples/real-world-examples/transactional-events-forwarder/go.mod

@@ -0,0 +1,37 @@
+module main.go
+
+go 1.17
+
+require (
+	github.com/ThreeDotsLabs/watermill v1.2.0-rc.7
+	github.com/ThreeDotsLabs/watermill-googlecloud v1.0.11
+	github.com/ThreeDotsLabs/watermill-sql v1.3.5
+	github.com/go-sql-driver/mysql v1.4.1
+)
+
+require (
+	cloud.google.com/go v0.97.0 // indirect
+	cloud.google.com/go/pubsub v1.17.0 // indirect
+	github.com/cenkalti/backoff/v3 v3.2.2 // indirect
+	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/google/go-cmp v0.5.6 // indirect
+	github.com/google/uuid v1.3.0 // indirect
+	github.com/googleapis/gax-go/v2 v2.1.1 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
+	github.com/lithammer/shortuuid/v3 v3.0.7 // indirect
+	github.com/oklog/ulid v1.3.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	go.opencensus.io v0.23.0 // indirect
+	golang.org/x/net v0.0.0-20211008194852-3b03d305991f // indirect
+	golang.org/x/oauth2 v0.0.0-20211005180243-6b3c2da341f1 // indirect
+	golang.org/x/sync v0.0.0-20210220032951-036812b2e83c // indirect
+	golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac // indirect
+	golang.org/x/text v0.3.7 // indirect
+	google.golang.org/api v0.59.0 // indirect
+	google.golang.org/appengine v1.6.7 // indirect
+	google.golang.org/genproto v0.0.0-20211028162531-8db9c33dc351 // indirect
+	google.golang.org/grpc v1.41.0 // indirect
+	google.golang.org/protobuf v1.27.1 // indirect
+)