cookie

* 이 글은 https://www.npmjs.com/package/cookie 번역하였습니다. 

 

HTTP 쿠키 parser와 HTTP 서버를 위한 serializer 입니다.

#1: Installation

cookie는 npm을 통해 이용가능한 Node.js 모듈입니다. npm install 코맨드를 사용하여 해당 모듈을 인스톨 할 수 있습니다.

$ npm install cookie

#2: API

var cookie = require('cookie');

cookie.parse(str, options)

str

HTTP cookie 헤더 값을 파싱하고 {name : value} 객체 형식으로 반환합니다. "str"인자는 cookie 헤더 값을 나타내는 문자열이고, "options"는 부가적인 파싱 옵션을 포함하는 선택적 개체입니다. 

var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2');
// { foo: 'bar', equation: 'E=mc^2' }

options

아래의 부가적인 파싱 옵션들을 허용합니다. 

 

@ decode 

cookie의 헤더의 값을 디코딩하는데 사용할 함수를 지정합니다. cookie의 값은 제한된 character set을 가지고 있기 때문에, 사용되는 함수는 이전에 인코딩이 된 cookie의 값을 javaScript 문자열 또는 다른 객체로 디코딩하는 데 사용합니다. 

디폴트 함수는 인코딩이 된 시퀀스를 바이트로 표현하기 위해 디코딩하는 decodeURIComponent 입니다. 

* Note: 지정한 함수가 에러가 나면 디코드가 안된 본래의 cookie의 값을 반환합니다. 

---

cookie.serialize(name, value, options)

name, value 

cookie의 이름과 값을 Set-Cookie 헤더의 문자열로 직렬화합니다. name 인자는 쿠키의 이름이고 value 인자는 쿠키의 셋팅되는 값입니다. 그리고 options 인자는 부가적인 파싱 옵션을 포함하는 선택적 개체입니다. 

var setCookie = cookie.serialize('foo', 'bar');
// foo=bar

options

cookie.serialize에서는 아래의 부가적인 옵션들을 허용합니다.

 

@ domain

Cookie 헤더 domain의 set할 값을 지정합니다. 디폴트로 아무런 값이 셋팅되지 않으며, 대부분의 클라이언트는 현재 도메인에만 적용되는 쿠키를 고려합니다. 

 

@ encode

cookie의 헤더의 값을 인코딩하는데 사용할 함수를 지정합니다. cookie의 값은 제한된 character set을 가지고 있기 때문에, 사용되는 함수는 값을 cookie의 값의 적절한 문자열로 인코딩하는 데 사용합니다.

디폴트 함수는 javaScript 문자열을 UTF-8 바이트 시퀀스로 인코딩한 다음 cookie 범위를 벗어난 모든 항목을 URL 인코딩하는 encodeURIComponent 입니다. 

 

@ expires

Cookie 헤더 Expires의 set할 Date 값을 지정합니다. 디폴트로 아무런 값이 셋팅되지 않으며, 대부분의 클라이언트는 "비 영구적인 cookie"를 사용하고 웹 브라우저를 종료 했을 때 이를 지웁니다. 

* Note: cookie 저장소 모델 사양에 따라 만료 및 maxAge가 모두 설정되면 maxAge가 우선권을 갖지만 모든 클라이언트가 이를 준수하는 것은 아니므로 둘 다 설정하면 동일한 날짜와 시간을 가리켜야합니다.

@ httpOnly

Cookie 헤더 httpOnly의 set할 속성 값(Boolean)을 지정합니다. 값이 true인 경우, httpOnly 속성이 적용되지만, false인 경우 httpOnly 속성은 적용되지 않습니다. 

* Note: 보통은 클라이언트 사이드 쪽 javaScript의 document.cookie에서 쿠키를 보는 것을 허용하지 않기 때문에, 값을 true로 적용하는 것은 신중해야 합니다.

@ maxAge

Cookie 헤더 Max-age의 set할 속성 값(Number)을 지정합니다. 적용한 number 값은 내림되어 integer 값으로 치환됩니다. 디폴트로 아무런 값이 셋팅되지 않습니다. 

* Note: cookie 저장소 모델 사양에 따라 만료 및 maxAge가 모두 설정되면 maxAge가 우선권을 갖지만 모든 클라이언트가 이를 준수하는 것은 아니므로 둘 다 설정하면 동일한 날짜와 시간을 가리켜야합니다.

@ path

Cookie 헤더 Path의 set할 속성 값을 지정합니다. 디폴트로 "defalut path"로 적용됩니다.

 

@ sameSite

Cookie 헤더 SameSite의 set할 속성 값(String or boolean)을 지정합니다. 

- 값을 true로 지정할 경우, 엄격한 모드로 동일한 사이트만 접근할 수 있도록 설정합니다.

- 값을 false로 지정할 경우, SameSite의 속성을 설정하지 않습니다. 

- 값을 'lax'로 지정할 경우, 느슨한 모드로 동일한 사이트만 접근할 수 있도록 설정합니다.

- 값을 'none'으로 지정할 경우, 교차 사이트 쿠키에 대해 SameSite 속성을 없음으로 설정합니다.

- 값을 'strict'으로 지정할 경우, 엄격한 모드로 동일한 사이트만 접근할 수 있도록 설정합니다.

 

다양한 모드에 대한 많은 정보는 이곳에서 찾아볼 수 있습니다.

* Note: sameSite의 속성값은 완벽하게 표준화되어 있지 않고, 추후에도 바뀔 수 있는 부분이 있습니다. 그래서 대부분의 클라이언트들은 이 속성값을 이해할때 까진 무시하기도 합니다. 

@secure

Cookie 헤더 Secure의 set할 속성 값(boolean)을 지정합니다. 값이 true인 경우, Secure속성이 적용되지만, false인 경우 Secure속성은 적용되지 않습니다. 디폴트 값은 false 입니다. 

* Note: 브라우저의 https가 적용이 되지 않은 경우, 호환성을 준수하는 클라이언트는 cookie를 server로 돌려 보내지 않기 때문에, 값을 true로 적용하는 것은 신중해야 합니다.

#3: Example

아래의 예시는 유저의 이름을 기억하고 나중에 방문하였을 때 다시 표시하기 위해서 Node.js core HTTP sever와 함께 cookie 모듈을 사용한 것입니다.

var cookie = require('cookie');
var escapeHtml = require('escape-html');
var http = require('http');
var url = require('url');
 
function onRequest(req, res) {
  // Parse the query string
  var query = url.parse(req.url, true, true).query;
 
  if (query && query.name) {
    // Set a new cookie with the name
    res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {
      httpOnly: true,
      maxAge: 60 * 60 * 24 * 7 // 1 week
    }));
 
    // Redirect back after setting cookie
    res.statusCode = 302;
    res.setHeader('Location', req.headers.referer || '/');
    res.end();
    return;
  }
 
  // Parse the cookies on the request
  var cookies = cookie.parse(req.headers.cookie || '');
 
  // Get the visitor name set in the cookie
  var name = cookies.name;
 
  res.setHeader('Content-Type', 'text/html; charset=UTF-8');
 
  if (name) {
    res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');
  } else {
    res.write('<p>Hello, new visitor!</p>');
  }
 
  res.write('<form method="GET">');
  res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');
  res.end('</form>');
}
 
http.createServer(onRequest).listen(3000);

#4: Testing

$ npm test

#5: Benchmark

$ npm run bench

> cookie@0.3.1 bench cookie
> node benchmark/index.js

  http_parser@2.8.0
  node@6.14.2
  v8@5.1.281.111
  uv@1.16.1
  zlib@1.2.11
  ares@1.10.1-DEV
  icu@58.2
  modules@48
  napi@3
  openssl@1.0.2o

> node benchmark/parse.js

  cookie.parse

  6 tests completed.

  simple      x 1,200,691 ops/sec ±1.12% (189 runs sampled)
  decode      x 1,012,994 ops/sec ±0.97% (186 runs sampled)
  unquote     x 1,074,174 ops/sec ±2.43% (186 runs sampled)
  duplicates  x   438,424 ops/sec ±2.17% (184 runs sampled)
  10 cookies  x   147,154 ops/sec ±1.01% (186 runs sampled)
  100 cookies x    14,274 ops/sec ±1.07% (187 runs sampled)

#6: References

* RFC 6265: Http State Management Mechanism 

* Same-site Cookies

#7: License

MIT

---

< 참고자료 >

 

[사이트] #NPM

www.npmjs.com/package/cookie

 

<Library> cookie end