Connection API cookie support

This outline relates to bug 6994

Overview

Applications wishing to receive and set HTTP cookies when working with services using the Connection API currently have to parse and build the Set-Cookie and Cookie headers themselves. This enhancement aims to simplify this process by adding methods to the Connection API to work with the Cookie class.

Note: This enhancement is about simplifying the API for applications using the Connection API or implementing connection handlers that need to work with HTTP cookies. It makes no attempt to automatically manage the cookies sent from remote services (for that, see bug 5717).

Changes to Connection API

Add the following methods to Connection:

• public void addRequestCookie(Cookie cookie, boolean removeDuplicates)
  • Add cookie to end of list for request.
• public void addRequestCookies(List<Cookie> cookies, boolean removeDuplicates)
  • Add all cookies to end of list for request.
• public void setRequestCookies(List<Cookie> cookies, boolean removeDuplicates)
  • Replace all cookies for request.
• public List<Cookie> getRequestCookies()
  • Get a copy of the cookie list (including cloned cookie objects).
• public Set<String> getRequestCookieNames()
  • Get set of names of request cookies.
• public List<Cookie> getRequestCookie(String name)
  • Get a copy of the cookies matching supplied name.

Add the following method to Connection.Response:

• public List<Cookie> getResponseCookies()
  • Get a cloned copy of the cookie list.
• public Set<String> getResponseCookieNames()
  • Get set of names of response cookie.
• public List<Cookie> getResponseCookies(String name)
  • Get a copy of the cookies matching the supplied name.

Notes:

1. This is adding HTTP-specific methods to the Connection API but I think that this is a common-enough scenario to warrant this addition.
2. The behaviour when the application attempts to use these methods for other protocols will depend on the implementation decisions. The current expectation is that setting cookies will be ignored for most protocols (i.e. the Cookie header will only get built by the HTTP/HTTPS transport) and that getResponseCookies() will return the empty list (i.e. any Set-Cookie header is only interpreted by the HTTP/HTTPS transport).

In the simplest applications that make two calls to the same service in a single /request, one could write something like this...

:
conn2.setRequestCookies(resp1.getResponseCookies(), false);
:

If there are many calls, one could do...

:
List<Cookie> serviceCookies = new ArrayList<Cookie>;();
:
serviceCookies.addAll(resp1.getResponseCookies());
:
conn2.setRequestCookies(serviceCookies, true);
:
serviceCookies.addAll(resp2.getResponseCookies());
:
conn3.setRequestCookies(serviceCookies, true);
:

Changes to /connection context

The cookie values will be explicitly carried between the Connection API invocation and the HTTP(S) transport using newly defined keys in the /connection zone:

• /connection/request/cookies
• /connection/response/cookies

Notes:

1. The value of both keys will be defined to be of type List<Cookie>. Both the Connection API and HTTP(S) transport implementation will interpret a null value as equivalent to an empty list.
2. The only supplied protocol implementations to take notice of these keys will be http and https. The other protocols will neither read nor set these keys.
3. QUESTION: When, if ever, should destination processing delete cookies with unset domain or path?

HTTP transport behaviour

1. Before transmission, the domains and paths of all Cookie objects in /connection/request/cookies will be compared to the final target URL. Any cookies that have set domains or paths that do not match will not be included in the HTTP(S) request. However, all cookies with empty domains and paths will be transmitted.
   • If we ever implement automatic redirection following in the HTTP transport then the request cookies will be further pruned.
2. The Cookie isSecure() and isHttpOnly() flags will be inspected and honoured for HTTP/HTTPS transmission, as appropriate.
3. Each valid cookie is sent as an individual Cookie header value, before any headers specified by /connection/request/headers.
   • If an HTTP(S) request both includes a value in /connection/request/cookies and includes a manually set /connection/request/headers/Cookie value, then both sets of cookies will be sent.
4. If server includes a Set-Cookie header in its response, then it will be included in both /connection/response/cookies and as a String in /connection/response/headers/Set-Cookie (for backwards compatibility).

Flow support

It might be appropriate to add cookie support to the REST activities in zero.assemble.flow, perhaps following the named input convention we currently use for headers?

Note: The Cookie class is not yet serializable, which would probably need to be changed to use it in flow activity inputs and outputs.

TO BE COMPLETED

PHP support

TO BE COMPLETED