You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+19-22Lines changed: 19 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,26 +1,23 @@
1
-
# Idempotent endpoints in Laravel à la Stripe
1
+
# Laravel Playback
2
2
3
3
[](https://packagist.org/packages/swiftmade/playback)
Do you need idempotent endpoints in Laravel? This package handles just that.
7
+
_Idempotent endpoints in Laravel à la Stripe._
8
8
9
-
What's even idempotency? What should you care?
10
-
-https://stripe.com/docs/api/idempotent_requests
9
+
Playback gives you idempotent endpoints in Laravel, using Redis locks. [What's even idempotency, and why should I care?](https://stripe.com/docs/api/idempotent_requests)
11
10
12
11
## Features
13
12
14
-
- Apply it to a single route, or apply to your whole API...
15
-
- Works only for POST requests. Other endpoints are ignored.
16
-
- Smart enough to verify path + headers + body is identical before returning the response.
17
-
- Will record and play back 2xx and 5xx responses, without touching your controller again.
18
-
- Doesn't remember the response if there was a validation error (4xx). So it's safe to retry.
19
-
- Prevents race conditions using Laravel's support for cache locks.
13
+
- 📼 Records and plays back 2xx and 5xx responses, without running your controller code again.
14
+
- 🔐 Built-in validation to prevent attacks by stolen/guessed idempotency keys.
15
+
- ⚠️ Won't store the response if there was a validation error (4xx).
16
+
- 🏎 Prevents race conditions using atomical Redis locks.
20
17
21
18
## Installation
22
19
23
-
> 💡 Currently, we only support Laravel 8.x.
20
+
> 💡 Supports Laravel 8.x, Laravel 9.x on PHP 7.4, 8.0 or 8.1
24
21
25
22
1. You can install the package via composer:
26
23
@@ -45,7 +42,7 @@ Open `config/cache.php` and add a new store.
45
42
'driver' => 'redis',
46
43
// 👇🏻 Caution!
47
44
// You probably don't want to use the cache connection in production.
48
-
// Playback cache can grow to a huge size for busy applications.
45
+
// Playback cache can grow to a big size for busy applications.
49
46
// Make sure your redis instance is ready.
50
47
'connection' => 'cache',
51
48
],
@@ -56,7 +53,7 @@ Open `config/cache.php` and add a new store.
56
53
57
54
Just apply the `Swiftmade\Playback\Playback` middleware to your endpoints. There are many ways of doing it, so here's a link to the docs:
58
55
59
-
-https://laravel.com/docs/8.x/middleware
56
+
-https://laravel.com/docs/9.x/middleware
60
57
61
58
## Use
62
59
@@ -72,17 +69,17 @@ If the key is not found during the lookup, a race begins. The first request to a
72
69
73
70
#### Errors:
74
71
75
-
+**400 Bad Request**
76
-
If you get back status `400`, it means your request was not identical to the cached one. It's the client's responsibility to repeat the exact same request. This is also why another user can't steal a response just by stealing/guessing the idempotency key. The cookies/authentication token would be different, which fails the signature check.
72
+
-**400 Bad Request**
73
+
If you get back status `400`, it means your request was not identical to the cached one. It's the client's responsibility to repeat the exact same request. This is also why another user can't steal a response just by stealing/guessing the idempotency key. The cookies/authentication token would be different, which fails the signature check.
77
74
78
-
+**425 Too Early**
79
-
If you get this error, it means you retried too fast after your initial attempt. Don't panic and try again a second later or so. It's perfectly safe to do so!
75
+
-**425 Too Early**
76
+
If you get this error, it means you retried too fast after your initial attempt. Don't panic and try again a second later or so. It's perfectly safe to do so!
80
77
81
78
🚨 Pro tip: If your controller action returns 4xx or 3xx status code, Playback won't cache the response. It's your responsibility to ensure no side effects take place (or they are rolled back) if a validation fails, a related db record was not found, etc and therefore the response status is 4xx or 3xx.
82
79
83
80
### Testing
84
81
85
-
```bash
82
+
```bash
86
83
composer test
87
84
```
88
85
@@ -100,9 +97,9 @@ If you discover any security related issues, please email [email protected] ins
100
97
101
98
## Credits
102
99
103
-
-[Ahmet Özisik](https://github.com/swiftmade)
104
-
-[All Contributors](../../contributors)
100
+
-[Ahmet Özisik](https://github.com/swiftmade)
101
+
-[All Contributors](../../contributors)
105
102
106
103
## License
107
104
108
-
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
105
+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
0 commit comments