Cookies
An HTTP cookie is a small piece of data stored by the user's browser. Cookies were designed to be a reliable mechanism for websites to remember stateful information. When the user visits the website again, the cookie is automatically sent with the request.
Integration
Spry is more focused on routing and APIs servers and does not have built-in support for Cookies.
Install Spry cookies support package (spry_cookie
):
dart pub add spry_cookie
Or, update your pubspec.yaml
file:
dependencies:
spry_cookie: <latest | ^{version}>
Usege
Spry Cookies supports global and single handler mode.
Global Support Cookies Recommended
import 'package:spry_cookie/spry_cookie.dart';
app.use(cookie());
Only single handler
Wrap a closure handler with cookieWith
:
import 'package:spry_cookie/spry_cookie.dart';
app.get('/user', cookieWith((event) {
// ...
}));
Sign/Unsign cookies
Spray Cookie supports signed and unsigned cookies. You only need to configure the security key and hash algorithm:
app.use(cookie(
secret: "Your cookie sign secret",
));
By default, the SHA-256
hash algorithm is used. If you want to customize it, please set algorithm
:
import 'package:crypto/crypto.dart';
app.use(cookie(
secret: "Your cookie sign secret",
algorithm: md5, // Set algorithm to MD5
));
Automatic secure
settings
使用 autoSecureSet
选项,当 Handler 中未设置 secure
时候,会判断当前请求是否是 https
自动设置:
app.use(cookie(
autoSecureSet: true
));
Cookie options
domain
Specifies the value for the Domain Set-Cookie attribute. By default, no domain is set, and most clients will consider the cookie to apply to only the current domain.
expires
Specifies the DateTime
to be the value for the Expires Set-Cookie attribute. By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application.
TIP
the cookie storage model specification states that if both expires
and maxAge
are set, then maxAge
takes precedence, but it is possible not all clients by obey this, so if both are set, they should point to the same date and time.
httpOnly
Specifies the boolean value for the HttpOnly Set-Cookie attribute. When truthy, the HttpOnly
attribute is set, otherwise it is not. By default, the HttpOnly
attribute is not set.
maxAge
Specifies the int
(in seconds) to be the value for the Max-Age Set-Cookie attribute. The given number will be converted to an integer by rounding down. By default, no maximum age is set.
partitioned
Specifies the bool?
value for the Partitioned Set-Cookie attribute. When truthy, the Partitioned
attribute is set, otherwise it is not. By default, the Partitioned
attribute is not set.
path
Specifies the value for the Path Set-Cookie attribute. By default, the path is considered the "default path".
secure
Specifies the boolean value for the Secure Set-Cookie attribute. When truthy, the Secure
attribute is set, otherwise it is not. By default, the Secure
attribute is not set.
sameSite
Specifies the SameSite
enum to be the value for the SameSite Set-Cookie attribute.
SameSite.lax
: will set theSameSite
attribute toLax
for lax same site enforcement.SameSite.none
: will set theSameSite
attribute toNone
for an explicit cross-site cookie.SameSite.strict
: will set theSameSite
attribute toStrict
for strict same site enforcement.
Managing cookies
We extend the Event
object to add a cookies
object to manage Cookies:
app.use((event) {
print(event.cookie.get("user_id"));
});
event.cookies.get
Gets a Request/Response cookie value.
event.cookies.getAll
Gets all Request/Response cookies list.
event.cookies.set
Sets a new cookie.
event.cookies.delete
Deletes a cookie.
event.cookies.serialize
Serialize a cookie.