Skip to content

Commit 2a6d198

Browse files
marickvantuilmarickvantuil
committed
Update README.md
1 parent 33b4a1f commit 2a6d198

File tree

4 files changed

+122
-92
lines changed

4 files changed

+122
-92
lines changed

‎README.md

Lines changed: 122 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<p align="center">
2-
<img src="/logo.png" width="400">
2+
<img src="/assets/logo.png" width="400">
33
</p>
44
<p align="center">
55
<img src="https://github.com/stackkit/laravel-google-cloud-tasks-queue/workflows/Run%20tests/badge.svg?branch=master" alt="Build Status">
@@ -9,135 +9,163 @@
99

1010
# Introduction
1111

12-
This package allows you to use Google Cloud Tasks as your queue driver.
12+
This package allows Google Cloud Tasks to be used as the queue driver.
1313

14-
# How it works
15-
16-
Using Cloud Tasks as a Laravel queue driver is fundamentally different than other Laravel queue drivers, like Redis.
17-
18-
Typically a Laravel queue has a worker that listens to incoming jobs using the `queue:work` / `queue:listen` command.
19-
With Cloud Tasks, this is not the case. Instead, Cloud Tasks will schedule the job for you and make an HTTP request to your application with the job payload. There is no need to run a `queue:work/listen` command.
20-
21-
For more information on how to configure the Cloud Tasks queue, read the next section [Configuring the queue](#configuring-the-queue)
22-
23-
This package uses the HTTP request handler and doesn't support AppEngine. But feel free to contribute!
14+
<p align="center">
15+
<img src="/assets/cloud-tasks-home.png" width="100%">
16+
</p>
2417

25-
# Requirements
18+
<details>
19+
<summary>
20+
Requirements
21+
</summary>
2622

27-
This package requires Laravel 5.6 or higher.
23+
<br>
24+
This package requires Laravel 6 or higher.
2825

2926
Please check the table below for supported Laravel and PHP versions:
3027

3128
|Laravel Version| PHP Version |
32-
|---|---|
33-
| 6.x | 7.2 or 7.3 or 7.4 or 8.0
34-
| 7.x | 7.2 or 7.3 or 7.4 or 8.0
35-
| 8.x | 7.3 or 7.4 or 8.0 or 8.1
29+
|---|---|
30+
| 6.x | 7.4 or 8.0
31+
| 7.x | 7.4 or 8.0
32+
| 8.x | 7.4 or 8.0 or 8.1
3633
| 9.x | 8.0 or 8.1
37-
38-
# Installation
34+
</details>
35+
<details>
36+
<summary>Installation</summary>
37+
<br>
3938

4039
(1) Require the package using Composer
4140

42-
```bash
43-
composer require stackkit/laravel-google-cloud-tasks-queue
44-
```
41+
```bash
42+
composer require stackkit/laravel-google-cloud-tasks-queue
43+
```
4544

4645

4746
[Official documentation - Creating Cloud Tasks queues](https://cloud.google.com/tasks/docs/creating-queues)
4847

4948
(2) Add a new queue connection to `config/queue.php`
5049

51-
```
52-
'cloudtasks' => [
53-
'driver' => 'cloudtasks',
54-
'project' => env('STACKKIT_CLOUD_TASKS_PROJECT', ''),
55-
'location' => env('STACKKIT_CLOUD_TASKS_LOCATION', ''),
56-
'handler' => env('STACKKIT_CLOUD_TASKS_HANDLER', ''),
57-
'queue' => env('STACKKIT_CLOUD_TASKS_QUEUE', 'default'),
58-
'service_account_email' => env('STACKKIT_CLOUD_TASKS_SERVICE_EMAIL', ''),
59-
],
60-
```
50+
```
51+
'cloudtasks' => [
52+
'driver' => 'cloudtasks',
53+
'project' => env('STACKKIT_CLOUD_TASKS_PROJECT', ''),
54+
'location' => env('STACKKIT_CLOUD_TASKS_LOCATION', ''),
55+
'handler' => env('STACKKIT_CLOUD_TASKS_HANDLER', ''),
56+
'queue' => env('STACKKIT_CLOUD_TASKS_QUEUE', 'default'),
57+
'service_account_email' => env('STACKKIT_CLOUD_TASKS_SERVICE_EMAIL', ''),
58+
],
59+
```
6160

6261
(3) Update the `QUEUE_CONNECTION` environment variable
6362

64-
```
65-
QUEUE_CONNECTION=cloudtasks
66-
```
63+
```
64+
QUEUE_CONNECTION=cloudtasks
65+
```
6766

6867
(4) [Laravel ^8.0 and above only] configure failed tasks to use the `database-uuids` driver in `config/queue.php`
6968

70-
```
71-
'failed' => [
72-
'database' => env('DB_CONNECTION', 'mysql'),
73-
'table' => 'failed_jobs',
74-
'driver' => 'database-uuids',
75-
],
76-
```
77-
78-
(5) Create a new Cloud Tasks queue using `gcloud`
79-
80-
````bash
81-
gcloud tasks queues create [QUEUE_ID]
82-
````
69+
```
70+
'failed' => [
71+
'database' => env('DB_CONNECTION', 'mysql'),
72+
'table' => 'failed_jobs',
73+
'driver' => 'database-uuids',
74+
],
75+
```
8376

8477
Now that the package is installed, the final step is to set the correct environment variables.
8578

8679
Please check the table below on what the values mean and what their value should be.
8780

88-
|Environment variable|Description|Example
89-
|---|---|---
90-
|`STACKKIT_CLOUD_TASKS_PROJECT`|The project your queue belongs to.|`my-project`
91-
|`STACKKIT_CLOUD_TASKS_LOCATION`|The region where the AppEngine is hosted|`europe-west6`
92-
|`STACKKIT_CLOUD_TASKS_HANDLER`|The URL that Cloud Tasks will call to process a job. This should be the URL to your Laravel app with the `handle-task` path added|`https://<your website>.com/handle-task`
93-
|`STACKKIT_CLOUD_TASKS_QUEUE`|The queue a job will be added to|`emails`
94-
|`STACKKIT_CLOUD_TASKS_SERVICE_EMAIL`|The email address of the AppEngine service account. Important, it should have the *Cloud Tasks Enqueuer* role. This is used for securing the handler.|`[email protected]`
81+
|Environment variable| Description |Example
82+
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---
83+
|`STACKKIT_CLOUD_TASKS_PROJECT`| The project your queue belongs to. |`my-project`
84+
|`STACKKIT_CLOUD_TASKS_LOCATION`| The region where the AppEngine is hosted |`europe-west6`
85+
|`STACKKIT_CLOUD_TASKS_HANDLER`| The URL that Cloud Tasks will call to process a job. This should be the URL to your Laravel app with the `handle-task` path added |`https://<your website>.com/handle-task`
86+
|`STACKKIT_CLOUD_TASKS_QUEUE`| The queue a job will be added to |`emails`
87+
|`STACKKIT_CLOUD_TASKS_SERVICE_EMAIL`| The email address of the AppEngine service account. Important, it should have the correct roles. See the section below which roles. |`[email protected]`
88+
</details>
89+
<details>
90+
<summary>
91+
How it works
92+
</summary>
93+
<br>
94+
Using Cloud Tasks as a Laravel queue driver is fundamentally different than other Laravel queue drivers, like Redis.
95+
96+
Typically a Laravel queue has a worker that listens to incoming jobs using the `queue:work` / `queue:listen` command.
97+
With Cloud Tasks, this is not the case. Instead, Cloud Tasks will schedule the job for you and make an HTTP request to your application with the job payload. There is no need to run a `queue:work/listen` command.
98+
99+
For more information on how to configure the Cloud Tasks queue, read the next section [Configuring the queue](#configuring-the-queue)
100+
</details>
101+
<details>
102+
<summary>Dashboard (beta)</summary>
103+
<br>
104+
The package comes with a beautiful dashboard that can be used to monitor all queued jobs.
105+
106+
107+
<img src="/assets/dashboard.png" width="100%">
108+
109+
---
110+
111+
_Experimental_
95112

96-
## Dashboard
113+
The dashboard works by storing all outgoing tasks in a database table. When Cloud Tasks calls the application and this
114+
package handles the task, we will automatically update the tasks' status, attempts
115+
and possible exceptions.
97116

98-
The package comes with a dashboard that can be used to monitor all queued jobs.
117+
There is probably a (small) performance penalty because each task dispatch and handling does extra database read and writes.
118+
Also, the dashboard has not been tested with high throughput queues.
99119

100-
To make use of it, publish its assets:
120+
---
101121

102-
```
103-
php artisan vendor:publish --tag=cloud-tasks-assets
104-
```
105122

106-
We expose a dashboard at the /cloud-tasks URI.
123+
To make use of it, enable it through the `.env` file:
107124

125+
```
126+
CLOUD_TASKS_MONITOR_ENABLED=true
127+
CLOUD_TASKS_MONITOR_ENABLED=MySecretLoginPasswordPleaseChangeThis
128+
```
108129

109-
```php
110-
```
130+
Then publish its assets:
111131

112-
# Authentication
132+
```
133+
php artisan vendor:publish --tag=cloud-tasks
134+
```
135+
</details>
136+
<details>
137+
<summary>Authentication</summary>
138+
<br>
113139

114140
Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable with a path to the credentials file.
115141

116142
More info: https://cloud.google.com/docs/authentication/production
117-
118-
## Service Account Roles
143+
</details>
144+
<details>
145+
<summary>Service Account Roles</summary>
119146

120147
If you're not using your master service account (which have all of the abilities), you must add the following roles to make it works:
121148
1. App Engine Viewer
122149
2. Cloud Tasks Enqueuer
123150
3. Cloud Tasks Viewer
124151
4. Service Account User
125-
126-
# Configuring the queue
127-
128-
When you first create a queue using `gcloud tasks queues create`, the default settings will look something like this:
129-
130-
```
131-
rateLimits:
132-
maxBurstSize: 100
133-
maxConcurrentDispatches: 1000
134-
maxDispatchesPerSecond: 500.0
135-
retryConfig:
136-
maxAttempts: 100
137-
maxBackoff: 3600s
138-
maxDoublings: 16
139-
minBackoff: 0.100s
140-
```
152+
</details>
153+
<details>
154+
<summary>Configuring the queue</summary>
155+
<br>
156+
When you first create a queue using `gcloud tasks queues create`, the default settings will look something like this:
157+
158+
```
159+
rateLimits:
160+
maxBurstSize: 100
161+
maxConcurrentDispatches: 1000
162+
maxDispatchesPerSecond: 500.0
163+
retryConfig:
164+
maxAttempts: 100
165+
maxBackoff: 3600s
166+
maxDoublings: 16
167+
minBackoff: 0.100s
168+
```
141169

142170
## Configurable settings
143171

@@ -166,27 +194,29 @@ A task will be scheduled for retry between min_backoff and max_backoff duration
166194
The time between retries will double max_doublings times.
167195

168196
A task's retry interval starts at min_backoff, then doubles max_doublings times, then increases linearly, and finally retries retries at intervals of max_backoff up to max_attempts times.
169-
197+
170198
For example, if min_backoff is 10s, max_backoff is 300s, and max_doublings is 3, then the a task will first be retried in 10s. The retry interval will double three times, and then increase linearly by 2^3 * 10s. Finally, the task will retry at intervals of max_backoff until the task has been attempted max_attempts times. Thus, the requests will retry at 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s, ....
171199

172200
## Recommended settings for Laravel
173201

174202
To simulate a single `queue:work/queue:listen` process, simply set the `maxConcurrentDispatches` to 1:
175203

176-
```
177-
gcloud tasks queues update [QUEUE_ID] --max-concurrent-dispatches=1
178-
```
204+
```
205+
gcloud tasks queues update [QUEUE_ID] --max-concurrent-dispatches=1
206+
```
179207

180208
More information on configuring queues:
181209

182210
https://cloud.google.com/tasks/docs/configuring-queues
183-
184-
# Security
185-
186-
The job handler requires each request to have an OpenID token. In the installation step we set the service account email, and with that service account, Cloud Tasks will generate an OpenID token and send it along with the job payload to the handler.
211+
</details>
212+
<details>
213+
<summary>Security</summary>
214+
<br>
215+
The job handler requires each request to have an OpenID token. In the installation step we set the service account email, and with that service account, Cloud Tasks will generate an OpenID token and send it along with the job payload to the handler.
187216

188217
This package verifies that the token is digitally signed by Google. Only Google Tasks will be able to call your handler.
189218

190219
More information about OpenID Connect:
191220

192221
https://developers.google.com/identity/protocols/oauth2/openid-connect
222+
</details>

‎assets/cloud-tasks-home.png

1.04 MB
Loading

‎assets/dashboard.png

875 KB
Loading

‎logo.png renamed to ‎assets/logo.png

File renamed without changes.

0 commit comments

Comments
 (0)