Skip to content

Commit

Permalink
Update docs to reflect change of encoding/decoding
Browse files Browse the repository at this point in the history
  • Loading branch information
carhartl committed Mar 4, 2020
1 parent 04805be commit a462826
Show file tree
Hide file tree
Showing 3 changed files with 2 additions and 36 deletions.
28 changes: 0 additions & 28 deletions CONTRIBUTING.md
Expand Up @@ -54,31 +54,3 @@ _Note: we recommend cleaning all the browser cookies before running the tests, t
You can build automatically after a file change using the following command:

$ grunt watch

## Integration with server-side

js-cookie allows integrating the encoding test suite with solutions written in other server-side languages. To integrate successfully, the server-side solution need to execute the `test/encoding.html` file in it's integration testing routine with a web automation tool, like [Selenium](http://www.seleniumhq.org/). js-cookie test suite exposes an API to make this happen.

### ?integration_baseurl

Specify the base url to pass the cookies into the server through a query string. If `integration_baseurl` query is not present, then js-cookie will assume there's no server.

### window.global_test_results

After the test suite has finished, js-cookie exposes the global `window.global_test_results` property containing an Object Literal that represents the [QUnit's details](http://api.qunitjs.com/QUnit.done/). js-cookie also adds an additional property representing an Array containing the tests data.

### Handling requests

When js-cookie encoding tests are executed, it will request a url in the server through an iframe representing each test being run. js-cookie expects the server to handle the input and return the proper `Set-Cookie` headers in the response. js-cookie will then read the response and verify if the encoding is consistent with js-cookie default encoding mechanism

js-cookie will send some requests to the server from the baseurl in the format `/encoding?name=<cookie>`, where `<cookie>` represents the cookie-name to be read from the request.

The server should handle those requests, internally parsing the cookie from the request and writing it again. It must set an `application/json` content type containing an object literal in the content body with `name` and `value` keys, each representing the cookie-name and cookie-value decoded by the server-side implementation.

If the server fails to respond with this specification in any request, the related QUnit test will fail. This is to make sure the server-side implementation will always be in sync with js-cookie encoding tests for maximum compatibility.

### Projects using it

This hook is being used in the following projects:

- [Java Cookie](https://github.com/js-cookie/java-cookie).
8 changes: 2 additions & 6 deletions README.md
Expand Up @@ -12,10 +12,9 @@ A simple, lightweight JavaScript API for handling cookies
- No dependency
- Supports ES modules
- Supports AMD/CommonJS
- [RFC 6265](https://tools.ietf.org/html/rfc6265) compliant
- Useful [Wiki](https://github.com/js-cookie/js-cookie/wiki)
- Enable [custom encoding/decoding](#converters)
- **< 800 bytes** gzipped!
- **< 700 bytes** gzipped!

**If you're viewing this at https://github.com/js-cookie/js-cookie, you're reading the documentation for the master branch.
[View documentation for the latest release.](https://github.com/js-cookie/js-cookie/tree/latest#readme)**
Expand Down Expand Up @@ -166,12 +165,9 @@ _Note: The `.noConflict` method is not necessary when using AMD or CommonJS, thu

## Encoding

This project is [RFC 6265](http://tools.ietf.org/html/rfc6265#section-4.1.1) compliant. All special characters that are not allowed in the cookie-name or cookie-value are encoded with each one's UTF-8 Hex equivalent using [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding).
The only character in cookie-name or cookie-value that is allowed and still encoded is the percent `%` character, it is escaped in order to interpret percent input as literal.
Special characters that are not permitted in the cookie name (";" and "=") or cookie value (";") are encoded with their UTF-8 Hex equivalent using [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding).
Please note that the default encoding/decoding strategy is meant to be interoperable [only between cookies that are read/written by js-cookie](https://github.com/js-cookie/js-cookie/pull/200#discussion_r63270778). To override the default encoding/decoding strategy you need to use a [converter](#converters).

_Note: According to [RFC 6265](https://tools.ietf.org/html/rfc6265#section-6.1), your cookies may get deleted if they are too big or there are too many cookies in the same domain, [more details here](https://github.com/js-cookie/js-cookie/wiki/Frequently-Asked-Questions#why-are-my-cookies-being-deleted)._

## Cookie Attributes

Cookie attribute defaults can be set globally by creating an instance of the api via `withAttributes()`, or individually for each call to `Cookies.set(...)` by passing a plain object as the last argument. Per-call attributes override the default attributes.
Expand Down
2 changes: 0 additions & 2 deletions SERVER_SIDE.md
@@ -1,7 +1,5 @@
# Server-side integration

There are some servers that are not compliant with the [RFC 6265](http://tools.ietf.org/html/rfc6265). For those, some characters that are not encoded by JavaScript Cookie might be treated differently.

Here we document the most important server-side peculiarities and their workarounds. Feel free to send a [Pull Request](https://github.com/js-cookie/js-cookie/blob/master/CONTRIBUTING.md#pull-requests) if you see something that can be improved.

_Disclaimer: This documentation is entirely based on community provided information. The examples below should be used only as a reference._
Expand Down

0 comments on commit a462826

Please sign in to comment.