cookie_store 0.3.5

Manages cookies in accordance with RFC 6265

Cookie Store

A Cookie management plugin for HTTP/HTTPS connections.

Parses Set-Cookie headers and generates Cookie headers for requests, in accordance with RFC 6265¹.

Usage

Initialise a cookie store

CookieStore cookieStore = new CookieStore();

When you get a Set-Cookie header, pass it to the cookie store after stripping the "Set-Cookie:" portion

for(header in responseHeaders){
    if(header.key == "Set-Cookie"){
        cookieStore.updateCookies(header.value, requestDomain, requestPath);
    }
    //...
}

When you're making a request, either get the cookies and add them to your request

final String domain = "example.com"
final String path = domain + "/api/whatever";

List<Cookie> cookies = cookieStore.getCookiesForRequest(domain, path);

// Add cookies to your request in some custom way
// Send request

or have the cookie store build the header for you

final String domain = "example.com"
final String path = domain + "/api/whatever";

String cookieHeader = CookieStore.buildCookieHeader(
  cookieStore.getCookiesForRequest(domain, path));

// Send request

When you're done with the current session, call the onSessionEnded() method. What this means is up to you. On a browser, it usually means when all tabs from that domain are closed.

If the cookie storage is taking up too much memory, you may call the reduceSize(numCookies, force) method to shrink the cookie storage. This will try to clean up any expired or excessive cookies and return true if successful. See the method documentation for more details.

The Cookie object

The Cookie object has a fairly simple structure:

class Cookie {
  String name;
  String value;
  DateTime? expiryTime;
  String domain = "";
  late String path;
  DateTime creationTime;
  DateTime lastAccessTime;
  bool persistent = false;
  bool hostOnly = false;
  bool secure = false;
  bool httpOnly = false;

  Cookie(
    this.name,
    this.value, {
    DateTime? creationTime,
    DateTime? lastAccessTime,
  })  : creationTime = creationTime ?? DateTime.now(),
        lastAccessTime = lastAccessTime ?? DateTime.now();
}

Acceptable date formats

This library is very permissive with respect to parsing date formats provided by the server. The following are acceptable formats:

• RFC 6265
  • 23:59:59 1 jan 1970
  • 23:59:59 1 jan 70
• HTTP (RFC 2616)
  • Thu, 1 Jan 1970 23:59:59 GMT
  • Thursday, 1-Jan-1970 23:59:59 GMT
  • Thu Jan 1 23:59:59 1970
• Incorrect HTTP (RFC 2616, but with the wrong style day of week)
  • Thursday, 1 Jan 1970 23:59:59 GMT
  • Thu, 1-Jan-1970 23:59:59 GMT
  • Thursday Jan 1 23:59:59 1970