cson  Hex Artifact Content

Artifact e6b09ba61b4f1afaffc5e1c31451c2029f1ceb9e:

Wiki page [cson_session] by stephan 2011-05-09 17:58:44.
0000: 44 20 32 30 31 31 2d 30 35 2d 30 39 54 31 37 3a  D 2011-05-09T17:
0010: 35 38 3a 34 34 2e 37 31 30 0a 4c 20 63 73 6f 6e  58:44.710.L cson
0020: 5f 73 65 73 73 69 6f 6e 0a 50 20 62 66 37 35 37  _session.P bf757
0030: 30 66 36 30 66 61 62 36 65 30 36 64 32 64 34 39  0f60fab6e06d2d49
0040: 65 39 34 63 36 64 33 63 39 32 33 63 65 36 36 61  e94c6d3c923ce66a
0050: 65 65 30 0a 55 20 73 74 65 70 68 61 6e 0a 57 20  ee0.U stephan.W 
0060: 31 30 38 32 31 0a 3c 73 74 72 6f 6e 67 3e 41 43  10821.<strong>AC
0070: 48 54 55 4e 47 3a 20 54 48 49 53 20 50 41 47 45  HTUNG: THIS PAGE
0080: 20 49 53 20 4e 4f 57 20 4d 41 49 4e 54 41 49 4e   IS NOW MAINTAIN
0090: 45 44 20 49 4e 20 54 48 45 20 4e 45 57 20 57 49  ED IN THE NEW WI
00a0: 4b 49 3a 3c 2f 73 74 72 6f 6e 67 3e 20 5b 68 74  KI:</strong> [ht
00b0: 74 70 3a 2f 2f 77 68 69 6b 69 2e 77 61 6e 64 65  tp://whiki.wande
00c0: 72 69 6e 67 68 6f 72 73 65 2e 6e 65 74 2f 77 69  ringhorse.net/wi
00d0: 6b 69 73 2f 63 73 6f 6e 2f 3f 70 61 67 65 3d 63  kis/cson/?page=c
00e0: 73 6f 6e 5f 73 65 73 73 69 6f 6e 5d 0a 0a 0a 3c  son_session]...<
00f0: 68 31 3e 63 73 6f 6e 5f 73 65 73 73 69 6f 6e 3c  h1>cson_session<
0100: 2f 68 31 3e 0d 0a 0d 0a 54 68 65 20 3c 74 74 3e  /h1>....The <tt>
0110: 63 73 6f 6e 5f 73 65 73 73 69 6f 6e 3c 2f 74 74  cson_session</tt
0120: 3e 20 41 50 49 20 69 73 20 61 20 73 6d 61 6c 6c  > API is a small
0130: 20 65 78 74 65 6e 73 69 6f 6e 20 74 6f 20 74 68   extension to th
0140: 65 20 63 73 6f 6e 20 63 6f 72 65 20 77 68 69 63  e cson core whic
0150: 68 20 70 72 6f 76 69 64 65 73 20 61 6e 20 69 6e  h provides an in
0160: 74 65 72 66 61 63 65 20 77 68 69 63 68 20 64 65  terface which de
0170: 66 69 6e 65 73 20 6f 70 65 72 61 74 69 6f 6e 73  fines operations
0180: 20 6e 65 63 65 73 73 61 72 79 20 66 6f 72 20 6c   necessary for l
0190: 6f 61 64 69 6e 67 2f 73 74 6f 72 69 6e 67 20 0d  oading/storing .
01a0: 0a 70 65 72 73 69 73 74 65 6e 74 20 61 70 70 6c  .persistent appl
01b0: 69 63 61 74 69 6f 6e 20 73 65 73 73 69 6f 6e 73  ication sessions
01c0: 20 75 73 69 6e 67 20 63 73 6f 6e 2d 62 61 73 65   using cson-base
01d0: 64 20 4a 53 4f 4e 20 74 72 65 65 73 2e 20 49 74  d JSON trees. It
01e0: 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20   was originally 
01f0: 77 72 69 74 74 65 6e 20 61 73 20 70 61 72 74 20  written as part 
0200: 6f 66 20 5b 63 73 6f 6e 5f 63 67 69 5d 20 62 75  of [cson_cgi] bu
0210: 74 20 69 73 20 69 6e 64 65 70 65 6e 64 65 6e 74  t is independent
0220: 20 6f 66 20 74 68 61 74 20 63 6f 64 65 2e 0d 0a   of that code...
0230: 0d 0a 42 79 20 22 70 65 72 73 69 73 74 65 6e 74  ..By "persistent
0240: 20 73 65 73 73 69 6f 6e 22 20 77 65 20 6d 65 61   session" we mea
0250: 6e 20 61 20 4a 53 4f 4e 20 6f 62 6a 65 63 74 20  n a JSON object 
0260: 74 72 65 65 20 28 69 6e 20 74 68 69 73 20 63 61  tree (in this ca
0270: 73 65 2c 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  se, implemented 
0280: 61 73 20 63 73 6f 6e 20 6f 62 6a 65 63 74 20 74  as cson object t
0290: 72 65 65 73 29 20 77 68 69 63 68 20 77 65 20 63  rees) which we c
02a0: 61 6e 20 73 61 76 65 2f 6c 6f 61 64 20 74 6f 20  an save/load to 
02b0: 73 74 6f 72 65 2f 72 65 73 74 6f 72 65 20 61 70  store/restore ap
02c0: 70 6c 69 63 61 74 69 6f 6e 20 73 74 61 74 65 20  plication state 
02d0: 64 75 72 69 6e 67 20 73 75 62 73 65 71 75 65 6e  during subsequen
02e0: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 65  t application se
02f0: 73 73 69 6f 6e 73 2e 20 57 69 74 68 20 74 68 69  ssions. With thi
0300: 73 20 69 6e 20 70 6c 61 63 65 2c 20 61 70 70 6c  s in place, appl
0310: 69 63 61 74 69 6f 6e 73 20 63 61 6e 20 65 61 73  ications can eas
0320: 69 6c 79 20 73 61 76 65 2f 72 65 73 74 6f 72 65  ily save/restore
0330: 20 74 68 65 69 72 20 61 70 70 2d 73 70 65 63 69   their app-speci
0340: 66 69 63 20 73 74 61 74 65 20 74 6f 20 4a 53 4f  fic state to JSO
0350: 4e 2e 0d 0a 0d 0a 54 68 65 20 41 50 49 20 6f 6e  N.....The API on
0360: 6c 79 20 64 65 66 69 6e 65 73 20 74 68 65 20 28  ly defines the (
0370: 73 6d 61 6c 6c 29 20 69 6e 74 65 72 66 61 63 65  small) interface
0380: 20 6e 65 65 64 65 64 20 66 6f 72 20 6d 61 6e 61   needed for mana
0390: 67 69 6e 67 20 73 65 73 73 69 6f 6e 73 2c 20 61  ging sessions, a
03a0: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 73 70 65 63  nd does not spec
03b0: 69 66 79 20 68 6f 77 20 74 68 65 20 73 65 73 73  ify how the sess
03c0: 69 6f 6e 73 20 61 72 65 20 74 6f 20 62 65 20 73  ions are to be s
03d0: 74 6f 72 65 64 2e 20 54 68 65 20 6c 69 62 72 61  tored. The libra
03e0: 72 79 20 63 6f 6d 65 73 20 77 69 74 68 20 74 68  ry comes with th
03f0: 65 73 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ese implementati
0400: 6f 6e 73 2c 20 68 6f 77 65 76 65 72 3a 0d 0a 0d  ons, however:...
0410: 0a 20 20 20 2a 20 20 5b 63 73 6f 6e 5f 73 65 73  .   *  [cson_ses
0420: 73 6d 67 72 5f 66 69 6c 65 5d 3a 20 66 69 6c 65  smgr_file]: file
0430: 2d 62 61 73 65 64 20 73 74 6f 72 61 67 65 2e 20  -based storage. 
0440: 54 68 69 73 20 72 65 71 75 69 72 65 73 20 74 68  This requires th
0450: 61 74 20 74 68 65 20 75 73 65 72 20 61 63 63 6f  at the user acco
0460: 75 6e 74 20 75 6e 64 65 72 20 77 68 69 63 68 20  unt under which 
0470: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
0480: 69 73 20 72 75 6e 6e 69 6e 67 20 68 61 73 20 61  is running has a
0490: 63 63 65 73 73 20 74 6f 20 73 74 6f 72 65 20 68  ccess to store h
04a0: 69 73 20 73 65 73 73 69 6f 6e 20 28 6f 72 20 61  is session (or a
04b0: 74 20 6c 65 61 73 74 20 72 65 61 64 20 69 74 29  t least read it)
04c0: 2e 20 46 6f 72 20 6c 6f 63 61 6c 20 61 70 70 6c  . For local appl
04d0: 69 63 61 74 69 6f 6e 73 20 74 68 69 73 20 69 73  ications this is
04e0: 20 72 61 72 65 6c 79 20 61 20 70 72 6f 62 6c 65   rarely a proble
04f0: 6d 2c 20 62 75 74 20 63 61 6e 20 62 65 20 70 72  m, but can be pr
0500: 6f 62 6c 65 6d 20 77 68 65 6e 20 72 75 6e 20 61  oblem when run a
0510: 73 20 61 20 43 47 49 20 6f 6e 20 61 20 68 6f 73  s a CGI on a hos
0520: 74 65 72 20 77 68 65 72 65 20 43 47 49 20 61 70  ter where CGI ap
0530: 70 73 20 72 75 6e 20 61 73 20 61 20 64 69 66 66  ps run as a diff
0540: 65 72 65 6e 74 20 75 73 65 72 20 74 68 61 6e 20  erent user than 
0550: 74 68 65 20 61 63 63 6f 75 6e 74 20 68 6f 6c 64  the account hold
0560: 65 72 2e 0d 0a 20 20 20 2a 20 20 5b 63 73 6f 6e  er...   *  [cson
0570: 5f 73 65 73 73 6d 67 72 5f 63 70 64 6f 5d 3a 20  _sessmgr_cpdo]: 
0580: 75 73 65 73 20 61 20 64 61 74 61 62 61 73 65 20  uses a database 
0590: 61 73 20 74 68 65 20 62 61 63 6b 65 6e 64 2e 20  as the backend. 
05a0: 54 68 65 20 5b 68 74 74 70 3a 2f 2f 66 6f 73 73  The [http://foss
05b0: 69 6c 2e 77 61 6e 64 65 72 69 6e 67 68 6f 72 73  il.wanderinghors
05c0: 65 2e 6e 65 74 2f 72 65 70 6f 73 2f 63 70 64 6f  e.net/repos/cpdo
05d0: 2f 7c 63 70 64 6f 5d 20 64 61 74 61 62 61 73 65  /|cpdo] database
05e0: 20 61 63 63 65 73 73 20 61 62 73 74 72 61 63 74   access abstract
05f0: 69 6f 6e 20 6c 69 62 72 61 72 79 20 69 73 20 75  ion library is u
0600: 73 65 64 20 68 65 72 65 20 74 6f 20 73 75 70 70  sed here to supp
0610: 6f 72 74 20 61 6e 79 20 64 61 74 61 62 61 73 65  ort any database
0620: 20 69 74 20 73 75 70 70 6f 72 74 73 20 28 63 75   it supports (cu
0630: 72 72 65 6e 74 6c 79 20 4d 79 53 51 4c 20 76 35  rrently MySQL v5
0640: 20 61 6e 64 20 73 71 6c 69 74 65 33 29 2e 20 28   and sqlite3). (
0650: 63 70 64 6f 20 69 73 20 69 6e 63 6c 75 64 65 64  cpdo is included
0660: 20 69 6e 20 74 68 69 73 20 73 6f 75 72 63 65 20   in this source 
0670: 74 72 65 65 20 61 6e 64 20 6e 65 65 64 20 6e 6f  tree and need no
0680: 74 20 62 65 20 69 6e 73 74 61 6c 6c 65 64 20 73  t be installed s
0690: 65 70 61 72 61 74 65 6c 79 2e 29 20 57 68 65 6e  eparately.) When
06a0: 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 20 73   using sqlite3 s
06b0: 74 6f 72 61 67 65 20 74 68 65 20 64 61 74 61 62  torage the datab
06c0: 61 73 65 20 3c 65 6d 3e 61 6e 64 20 74 68 65 20  ase <em>and the 
06d0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
06e0: 6e 69 6e 67 20 69 74 3c 2f 65 6d 3e 20 6d 75 73  ning it</em> mus
06f0: 74 20 62 65 20 77 72 69 74 61 62 6c 65 20 62 79  t be writable by
0700: 20 74 68 65 20 75 73 65 72 20 61 63 63 6f 75 6e   the user accoun
0710: 74 20 75 6e 64 65 72 20 77 68 69 63 68 20 43 47  t under which CG
0720: 49 73 20 61 72 65 20 72 75 6e 2e 20 54 68 69 73  Is are run. This
0730: 20 69 73 20 62 65 63 61 75 73 65 20 73 71 6c 69   is because sqli
0740: 74 65 33 20 63 72 65 61 74 65 73 20 61 20 74 65  te3 creates a te
0750: 6d 70 6f 72 61 72 79 20 6a 6f 75 72 6e 61 6c 20  mporary journal 
0760: 66 69 6c 65 20 74 68 65 72 65 20 61 6e 64 20 77  file there and w
0770: 69 6c 6c 20 66 61 69 6c 20 69 66 20 69 74 20 63  ill fail if it c
0780: 61 6e 6e 6f 74 20 63 72 65 61 74 65 20 69 74 2e  annot create it.
0790: 0d 0a 20 20 20 2a 20 20 5b 63 73 6f 6e 5f 73 65  ..   *  [cson_se
07a0: 73 73 6d 67 72 5f 77 68 69 6f 5f 68 74 5d 3a 20  ssmgr_whio_ht]: 
07b0: 61 20 66 69 6c 65 2d 62 61 73 65 64 20 73 68 61  a file-based sha
07c0: 72 65 64 20 68 61 73 68 74 61 62 6c 65 2c 20 77  red hashtable, w
07d0: 68 65 72 65 20 73 65 73 73 69 6f 6e 20 49 44 73  here session IDs
07e0: 20 61 72 65 20 74 68 65 20 6b 65 79 73 20 61 6e   are the keys an
07f0: 64 20 4a 53 4f 4e 20 64 61 74 61 20 61 72 65 20  d JSON data are 
0800: 74 68 65 20 76 61 6c 75 65 73 2e 20 49 74 20 69  the values. It i
0810: 73 20 62 61 73 65 64 20 6f 6e 20 5b 68 74 74 70  s based on [http
0820: 3a 2f 2f 66 6f 73 73 69 6c 2e 77 61 6e 64 65 72  ://fossil.wander
0830: 69 6e 67 68 6f 72 73 65 2e 6e 65 74 2f 72 65 70  inghorse.net/rep
0840: 6f 73 2f 77 68 69 6f 2f 69 6e 64 65 78 2e 63 67  os/whio/index.cg
0850: 69 2f 77 69 6b 69 2f 77 68 69 6f 5f 68 74 7c 77  i/wiki/whio_ht|w
0860: 68 69 6f 5f 68 74 5d 2c 20 61 6e 64 20 74 68 61  hio_ht], and tha
0870: 74 20 63 6f 64 65 20 69 73 20 69 6e 63 6c 75 64  t code is includ
0880: 65 64 20 69 6e 20 74 68 69 73 20 74 72 65 65 2e  ed in this tree.
0890: 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 64 6f   The makefile do
08a0: 65 73 20 6e 6f 74 20 62 75 69 6c 64 20 74 68 69  es not build thi
08b0: 73 20 6f 6e 65 20 62 79 20 64 65 66 61 75 6c 74  s one by default
08c0: 20 62 65 63 61 75 73 65 20 28 41 29 20 69 27 6d   because (A) i'm
08d0: 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 20 6c 69   the only one li
08e0: 6b 65 6c 79 20 74 6f 20 75 73 65 20 69 74 20 61  kely to use it a
08f0: 6e 64 20 28 42 29 20 69 74 20 72 65 71 75 69 72  nd (B) it requir
0900: 65 73 20 69 6e 63 6c 75 64 69 6e 67 2f 6c 69 6e  es including/lin
0910: 6b 69 6e 67 20 61 20 68 75 67 65 20 61 6d 6f 75  king a huge amou
0920: 6e 74 20 6f 66 20 65 78 74 65 72 6e 61 6c 20 63  nt of external c
0930: 6f 64 65 20 66 72 6f 6d 20 5b 68 74 74 70 3a 2f  ode from [http:/
0940: 2f 66 6f 73 73 69 6c 2e 77 61 6e 64 65 72 69 6e  /fossil.wanderin
0950: 67 68 6f 72 73 65 2e 6e 65 74 2f 72 65 70 6f 73  ghorse.net/repos
0960: 2f 77 68 69 6f 2f 7c 6c 69 62 77 68 69 6f 5d 2e  /whio/|libwhio].
0970: 0d 0a 20 20 20 2a 20 20 5b 63 73 6f 6e 5f 73 65  ..   *  [cson_se
0980: 73 73 6d 67 72 5f 77 68 69 6f 5f 65 70 66 73 5d  ssmgr_whio_epfs]
0990: 3a 20 61 6e 20 22 65 6d 62 65 64 64 65 64 20 66  : an "embedded f
09a0: 69 6c 65 73 79 73 74 65 6d 22 20 63 6f 6e 74 61  ilesystem" conta
09b0: 69 6e 65 72 20 66 69 6c 65 2c 20 62 61 73 65 64  iner file, based
09c0: 20 6f 6e 20 5b 68 74 74 70 3a 2f 2f 66 6f 73 73   on [http://foss
09d0: 69 6c 2e 77 61 6e 64 65 72 69 6e 67 68 6f 72 73  il.wanderinghors
09e0: 65 2e 6e 65 74 2f 72 65 70 6f 73 2f 77 68 69 6f  e.net/repos/whio
09f0: 2f 69 6e 64 65 78 2e 63 67 69 2f 77 69 6b 69 2f  /index.cgi/wiki/
0a00: 77 68 69 6f 5f 65 70 66 73 7c 6c 69 62 77 68 69  whio_epfs|libwhi
0a10: 6f 5f 65 70 66 73 5d 2e 20 4c 69 6b 65 20 74 68  o_epfs]. Like th
0a20: 65 20 68 61 73 68 74 61 62 6c 65 2d 62 61 73 65  e hashtable-base
0a30: 64 20 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 69 73  d solution, this
0a40: 20 6f 6e 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70   one is not comp
0a50: 69 6c 65 64 20 69 6e 20 62 79 20 64 65 66 61 75  iled in by defau
0a60: 6c 74 20 28 66 6f 72 20 74 68 65 20 73 61 6d 65  lt (for the same
0a70: 20 72 65 61 73 6f 6e 73 20 67 69 76 65 6e 20 61   reasons given a
0a80: 62 6f 76 65 29 2e 0d 0a 0d 0a 52 65 67 61 72 64  bove).....Regard
0a90: 69 6e 67 20 74 68 65 20 66 69 6c 65 2f 64 69 72  ing the file/dir
0aa0: 65 63 74 6f 72 79 20 70 65 72 6d 69 73 73 69 6f  ectory permissio
0ab0: 6e 73 20 66 6f 72 20 43 47 49 73 3a 20 6d 6f 73  ns for CGIs: mos
0ac0: 74 20 68 6f 73 74 65 72 73 20 28 69 6e 20 6d 79  t hosters (in my
0ad0: 20 65 78 70 65 72 69 65 6e 63 65 29 20 72 75 6e   experience) run
0ae0: 20 43 47 49 20 73 63 72 69 70 74 73 20 61 73 20   CGI scripts as 
0af0: 74 68 65 20 61 63 63 6f 75 6e 74 20 68 6f 6c 64  the account hold
0b00: 65 72 27 73 20 75 73 65 72 2c 20 61 6e 64 20 74  er's user, and t
0b10: 68 75 73 20 43 47 49 20 61 70 70 73 20 74 65 6e  hus CGI apps ten
0b20: 64 20 74 6f 20 68 61 76 65 20 66 75 6c 6c 20 61  d to have full a
0b30: 63 63 65 73 73 20 74 6f 20 61 6e 79 74 68 69 6e  ccess to anythin
0b40: 67 20 74 68 65 20 61 63 63 6f 75 6e 74 20 68 6f  g the account ho
0b50: 6c 64 65 72 20 68 61 73 2e 20 53 6f 6d 65 20 63  lder has. Some c
0b60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 73 20 6d 61  onfigurations ma
0b70: 79 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20  y, on the other 
0b80: 68 61 6e 64 2c 20 65 78 65 63 75 74 65 20 43 47  hand, execute CG
0b90: 49 20 73 63 72 69 70 74 73 20 61 73 2c 20 65 2e  I scripts as, e.
0ba0: 67 2e 2c 20 74 68 65 20 3c 74 74 3e 77 77 77 3c  g., the <tt>www<
0bb0: 2f 74 74 3e 20 6f 72 20 3c 74 74 3e 61 70 61 63  /tt> or <tt>apac
0bc0: 68 65 3c 2f 74 74 3e 20 75 73 65 72 2c 20 69 6e  he</tt> user, in
0bd0: 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
0be0: 73 65 73 73 69 6f 6e 20 73 74 6f 72 61 67 65 20  session storage 
0bf0: 68 61 73 20 74 6f 20 62 65 20 77 72 69 74 61 62  has to be writab
0c00: 6c 65 20 62 79 20 74 68 61 74 20 75 73 65 72 20  le by that user 
0c10: 28 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 63 61  (and probably ca
0c20: 6e 6e 6f 74 20 62 65 20 63 6c 65 61 6e 65 64 20  nnot be cleaned 
0c30: 75 70 20 62 79 20 74 68 65 20 61 63 63 6f 75 6e  up by the accoun
0c40: 74 20 68 6f 6c 64 65 72 21 29 2e 0d 0a 0d 0a 53  t holder!).....S
0c50: 65 65 20 74 68 65 20 66 69 6c 65 20 3c 74 74 3e  ee the file <tt>
0c60: 69 6e 63 6c 75 64 65 2f 77 68 2f 63 73 6f 6e 2f  include/wh/cson/
0c70: 63 73 6f 6e 5f 73 65 73 73 69 6f 6e 2e 68 3c 2f  cson_session.h</
0c80: 74 74 3e 20 66 6f 72 20 74 68 65 20 41 50 49 20  tt> for the API 
0c90: 64 6f 63 73 20 66 6f 72 20 66 75 6c 6c 20 64 65  docs for full de
0ca0: 74 61 69 6c 73 20 61 6e 64 20 69 6e 66 6f 72 6d  tails and inform
0cb0: 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 74 6f 20  ation on how to 
0cc0: 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 62 61  configure the ba
0cd0: 63 6b 2d 65 6e 64 73 20 66 6f 72 20 74 68 65 20  ck-ends for the 
0ce0: 6c 6f 63 61 6c 20 65 6e 76 69 72 6f 6e 6d 65 6e  local environmen
0cf0: 74 2e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  t. Configuration
0d00: 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 67 69 76   options are giv
0d10: 65 6e 20 61 73 20 63 73 6f 6e 2d 62 61 73 65 64  en as cson-based
0d20: 20 4a 53 4f 4e 20 74 72 65 65 73 2c 20 77 68 69   JSON trees, whi
0d30: 63 68 20 6d 65 61 6e 73 20 74 68 65 20 63 6f 6e  ch means the con
0d40: 66 69 67 75 72 61 74 69 6f 6e 20 64 61 74 61 20  figuration data 
0d50: 69 73 20 65 61 73 79 20 74 6f 20 69 6d 70 6f 72  is easy to impor
0d60: 74 20 66 72 6f 6d 20 4a 53 4f 4e 20 63 6f 6e 66  t from JSON conf
0d70: 69 67 20 66 69 6c 65 73 20 6f 72 20 74 6f 20 63  ig files or to c
0d80: 72 65 61 74 65 20 74 68 65 6d 20 70 72 6f 67 72  reate them progr
0d90: 61 6d 6d 61 74 69 63 61 6c 6c 79 2e 20 54 68 65  ammatically. The
0da0: 72 65 20 61 72 65 20 65 78 61 6d 70 6c 65 73 20  re are examples 
0db0: 6f 66 20 73 75 63 68 20 63 6f 6e 66 69 67 75 72  of such configur
0dc0: 61 74 69 6f 6e 20 64 65 74 61 69 6c 73 20 73 68  ation details sh
0dd0: 6f 77 6e 20 66 75 72 74 68 65 72 20 64 6f 77 6e  own further down
0de0: 20 6f 6e 20 74 68 69 73 20 70 61 67 65 2e 0d 0a   on this page...
0df0: 0d 0a 54 68 65 20 41 50 49 20 3c 65 6d 3e 64 6f  ..The API <em>do
0e00: 65 73 20 6e 6f 74 3c 2f 65 6d 3e 20 70 72 6f 76  es not</em> prov
0e10: 69 64 65 20 69 6e 74 65 72 66 61 63 65 73 20 66  ide interfaces f
0e20: 6f 72 20 68 61 6e 64 6c 69 6e 67 20 61 64 6d 69  or handling admi
0e30: 6e 69 73 74 72 61 74 69 76 65 20 64 65 74 61 69  nistrative detai
0e40: 6c 73 20 6c 69 6b 65 20 63 6c 65 61 6e 69 6e 67  ls like cleaning
0e50: 20 75 70 20 65 78 70 69 72 65 64 20 73 65 73 73   up expired sess
0e60: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 75 6e  ions from the un
0e70: 64 65 72 6c 79 69 6e 67 20 73 74 6f 72 61 67 65  derlying storage
0e80: 2e 20 49 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 74  . Implementing t
0e90: 68 65 73 65 20 74 68 69 6e 67 73 20 69 73 2c 20  hese things is, 
0ea0: 6d 6f 72 65 20 6f 66 74 65 6e 20 74 68 61 6e 20  more often than 
0eb0: 6e 6f 74 2c 20 6d 75 63 68 20 73 69 6d 70 6c 65  not, much simple
0ec0: 72 20 75 73 69 6e 67 20 62 61 63 6b 65 6e 64 2f  r using backend/
0ed0: 73 79 73 74 65 6d 2d 73 70 65 63 69 66 69 63 20  system-specific 
0ee0: 73 63 72 69 70 74 69 6e 67 20 74 68 61 6e 20 69  scripting than i
0ef0: 74 20 77 6f 75 6c 64 20 62 65 20 74 6f 20 64 6f  t would be to do
0f00: 20 69 74 20 69 6e 20 43 2e 20 57 65 20 61 6c 73   it in C. We als
0f10: 6f 20 63 61 6e 6e 6f 74 20 67 65 6e 65 72 69 63  o cannot generic
0f20: 61 6c 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 20 74  ally implement t
0f30: 68 65 20 63 6c 65 61 6e 75 70 20 6c 6f 67 69 63  he cleanup logic
0f40: 20 61 74 20 74 68 65 20 6c 69 62 72 61 72 79 20   at the library 
0f50: 6c 65 76 65 6c 2e 20 65 2e 67 2e 20 73 6f 6d 65  level. e.g. some
0f60: 20 63 6c 69 65 6e 74 73 20 6d 69 67 68 74 20 72   clients might r
0f70: 65 71 75 69 72 65 20 74 68 61 74 20 74 68 65 20  equire that the 
0f80: 73 65 73 73 69 6f 6e 20 73 74 6f 72 61 67 65 20  session storage 
0f90: 6e 6f 74 20 67 65 74 20 64 65 6c 65 74 65 64 2c  not get deleted,
0fa0: 20 62 75 74 20 67 65 74 20 6d 6f 76 65 64 20 74   but get moved t
0fb0: 6f 20 61 6e 20 61 72 63 68 69 76 65 2e 20 54 68  o an archive. Th
0fc0: 75 73 20 63 6c 65 61 6e 75 70 20 6f 66 20 73 74  us cleanup of st
0fd0: 61 6c 65 20 73 65 73 73 69 6f 6e 20 73 74 6f 72  ale session stor
0fe0: 61 67 65 20 69 73 20 6c 65 66 74 20 74 6f 20 74  age is left to t
0ff0: 68 65 20 73 79 73 74 65 6d 20 61 64 6d 69 6e 69  he system admini
1000: 73 74 72 61 74 6f 72 20 28 6f 72 20 64 65 76 65  strator (or deve
1010: 6c 6f 70 65 72 20 6f 66 20 74 68 65 20 63 6c 69  loper of the cli
1020: 65 6e 74 20 61 70 70 20 77 68 69 63 68 20 63 72  ent app which cr
1030: 65 61 74 65 73 20 74 68 65 20 73 65 73 73 69 6f  eates the sessio
1040: 6e 73 29 2e 20 41 20 70 65 72 69 6f 64 69 63 20  ns). A periodic 
1050: 63 72 6f 6e 20 6a 6f 62 2c 20 6f 72 20 61 70 70  cron job, or app
1060: 20 6c 6f 67 69 63 20 77 68 69 63 68 20 72 75 6e   logic which run
1070: 73 20 74 68 65 20 63 6c 65 61 6e 75 70 20 63 6f  s the cleanup co
1080: 6d 6d 61 6e 64 73 20 65 76 65 72 79 20 73 6f 20  mmands every so 
1090: 6f 66 74 65 6e 2c 20 61 72 65 20 6f 66 74 65 6e  often, are often
10a0: 20 76 69 61 62 6c 65 20 73 6f 6c 75 74 69 6f 6e   viable solution
10b0: 73 2e 0d 0a 0d 0a 49 74 20 69 73 20 69 6d 70 6f  s.....It is impo
10c0: 72 74 61 6e 74 20 74 6f 20 6e 6f 74 65 20 74 68  rtant to note th
10d0: 61 74 20 73 65 73 73 69 6f 6e 20 6d 61 6e 61 67  at session manag
10e0: 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 22 61 75  ement is not "au
10f0: 74 6f 6d 61 74 69 63 2e 22 20 54 68 65 20 63 6c  tomatic." The cl
1100: 69 65 6e 74 20 61 70 70 20 6d 75 73 74 20 64 6f  ient app must do
1110: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0d   the following:.
1120: 0a 0d 0a 20 20 20 2a 20 20 49 6e 73 74 61 6e 74  ...   *  Instant
1130: 69 61 74 65 20 61 20 73 65 73 73 69 6f 6e 20 6d  iate a session m
1140: 61 6e 61 67 65 72 20 69 6e 73 74 61 6e 63 65 20  anager instance 
1150: 28 43 20 63 6c 61 73 73 3d 3c 74 74 3e 63 73 6f  (C class=<tt>cso
1160: 6e 5f 73 65 73 73 6d 67 72 3c 2f 74 74 3e 29 20  n_sessmgr</tt>) 
1170: 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1180: 20 70 72 6f 76 69 64 65 64 20 66 61 63 74 6f 72   provided factor
1190: 79 20 66 75 6e 63 74 69 6f 6e 73 2e 20 28 4f 72  y functions. (Or
11a0: 20 72 6f 6c 6c 20 74 68 65 69 72 20 6f 77 6e 20   roll their own 
11b0: 2d 20 69 74 27 73 20 71 75 69 74 65 20 65 61 73  - it's quite eas
11c0: 79 2e 29 0d 0a 20 20 20 2a 20 20 47 65 6e 65 72  y.)..   *  Gener
11d0: 61 74 65 20 6f 72 20 61 63 71 75 69 72 65 20 61  ate or acquire a
11e0: 20 75 6e 69 71 75 65 20 49 44 20 66 6f 72 20 74   unique ID for t
11f0: 68 65 20 73 65 73 73 69 6f 6e 2e 20 48 6f 77 20  he session. How 
1200: 79 6f 75 20 64 6f 20 74 68 69 73 20 69 73 20 79  you do this is y
1210: 6f 75 72 20 62 75 73 69 6e 65 73 73 2e 20 28 69  our business. (i
1220: 20 6c 69 6b 65 20 55 55 49 44 73 2e 29 0d 0a 20   like UUIDs.).. 
1230: 20 20 2a 20 20 55 73 65 20 74 68 65 20 6d 61 6e    *  Use the man
1240: 61 67 65 72 20 74 6f 20 6c 6f 61 64 20 74 68 65  ager to load the
1250: 20 73 65 73 73 69 6f 6e 20 66 6f 72 20 61 20 67   session for a g
1260: 69 76 65 6e 20 75 6e 69 71 75 65 20 49 44 2e 20  iven unique ID. 
1270: 54 68 65 20 73 65 73 73 69 6f 6e 20 69 74 73 65  The session itse
1280: 6c 66 20 69 73 20 61 20 63 73 6f 6e 20 4a 53 4f  lf is a cson JSO
1290: 4e 20 6f 62 6a 65 63 74 20 74 72 65 65 20 77 68  N object tree wh
12a0: 69 63 68 20 63 61 6e 20 62 65 20 71 75 65 72 69  ich can be queri
12b0: 65 64 2f 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ed/modified by t
12c0: 68 65 20 63 6c 69 65 6e 74 20 74 6f 20 66 65 74  he client to fet
12d0: 63 68 2f 73 65 74 20 74 68 65 20 73 65 73 73 69  ch/set the sessi
12e0: 6f 6e 20 64 61 74 61 2e 0d 0a 20 20 20 2a 20 20  on data...   *  
12f0: 45 76 65 6e 74 75 61 6c 6c 79 20 75 73 65 20 74  Eventually use t
1300: 68 65 20 6d 61 6e 61 67 65 72 20 74 6f 20 73 61  he manager to sa
1310: 76 65 20 74 68 65 20 73 65 73 73 69 6f 6e 2e 0d  ve the session..
1320: 0a 20 20 20 2a 20 20 4f 70 74 69 6f 6e 61 6c 6c  .   *  Optionall
1330: 79 20 75 73 65 20 74 68 65 20 6d 61 6e 61 67 65  y use the manage
1340: 72 20 74 6f 20 64 65 6c 65 74 65 20 74 68 61 74  r to delete that
1350: 20 73 69 6e 67 6c 65 20 73 65 73 73 69 6f 6e 20   single session 
1360: 69 6e 73 74 61 6e 63 65 20 66 72 6f 6d 20 74 68  instance from th
1370: 65 20 73 74 6f 72 61 67 65 2e 0d 0a 20 20 20 2a  e storage...   *
1380: 20 20 46 72 65 65 20 74 68 65 20 73 65 73 73 69    Free the sessi
1390: 6f 6e 20 6d 61 6e 61 67 65 72 20 69 6e 73 74 61  on manager insta
13a0: 6e 63 65 20 28 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  nce (<em>not</em
13b0: 3e 20 75 73 69 6e 67 20 3c 74 74 3e 66 72 65 65  > using <tt>free
13c0: 28 29 3c 2f 74 74 3e 21 20 53 65 65 20 74 68 65  ()</tt>! See the
13d0: 20 41 50 49 20 64 6f 63 73 21 29 2e 0d 0a 0d 0a   API docs!).....
13e0: 54 68 65 20 5b 63 73 6f 6e 5f 63 67 69 5d 20 41  The [cson_cgi] A
13f0: 50 49 27 73 20 73 65 73 73 69 6f 6e 20 73 75 70  PI's session sup
1400: 70 6f 72 74 20 74 61 6b 65 73 20 63 61 72 65 20  port takes care 
1410: 6f 66 20 74 68 6f 73 65 20 64 65 74 61 69 6c 73  of those details
1420: 20 66 6f 72 20 63 6c 69 65 6e 74 73 20 6f 66 20   for clients of 
1430: 74 68 61 74 20 41 50 49 2c 20 6c 6f 61 64 69 6e  that API, loadin
1440: 67 20 61 6e 64 20 73 61 76 69 6e 67 20 74 68 65  g and saving the
1450: 20 73 65 73 73 69 6f 6e 2c 20 61 73 20 77 65 6c   session, as wel
1460: 6c 20 61 73 20 74 72 61 63 6b 69 6e 67 20 61 20  l as tracking a 
1470: 73 65 73 73 69 6f 6e 20 49 44 20 76 69 61 20 61  session ID via a
1480: 6e 20 48 54 54 50 20 63 6f 6f 6b 69 65 2c 20 6c  n HTTP cookie, l
1490: 65 61 76 69 6e 67 20 74 68 65 20 63 6c 69 65 6e  eaving the clien
14a0: 74 20 6f 6e 6c 79 20 74 6f 20 70 72 6f 76 69 64  t only to provid
14b0: 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
14c0: 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ion information 
14d0: 61 6e 64 20 64 65 61 6c 20 77 69 74 68 20 74 68  and deal with th
14e0: 65 20 61 63 74 75 61 6c 20 4a 53 4f 4e 20 6f 62  e actual JSON ob
14f0: 6a 65 63 74 20 74 72 65 65 2e 0d 0a 0d 0a 3c 68  ject tree.....<h
1500: 31 3e 4d 65 6d 6f 72 79 20 61 6e 64 20 53 74 6f  1>Memory and Sto
1510: 72 61 67 65 20 43 6f 73 74 73 3c 2f 68 31 3e 0d  rage Costs</h1>.
1520: 0a 0d 0a 54 68 65 20 6d 65 6d 6f 72 79 20 63 6f  ...The memory co
1530: 73 74 20 6f 66 20 61 20 73 65 73 73 69 6f 6e 20  st of a session 
1540: 6d 61 6e 61 67 65 72 20 6f 62 6a 65 63 74 20 69  manager object i
1550: 73 2c 20 69 6e 20 61 6e 64 20 6f 66 20 69 74 73  s, in and of its
1560: 65 6c 66 2c 20 76 65 72 79 20 6c 6f 77 20 28 77  elf, very low (w
1570: 65 6c 6c 20 75 6e 64 65 72 20 31 30 30 20 62 79  ell under 100 by
1580: 74 65 73 2c 20 6e 6f 74 20 63 6f 75 6e 74 69 6e  tes, not countin
1590: 67 20 74 68 65 20 61 63 74 75 61 6c 20 75 6e 64  g the actual und
15a0: 65 72 6c 79 69 6e 67 20 73 74 6f 72 61 67 65 20  erlying storage 
15b0: 68 61 6e 64 6c 65 29 2e 20 54 68 65 20 63 6f 6e  handle). The con
15c0: 63 72 65 74 65 20 73 74 6f 72 61 67 65 20 74 79  crete storage ty
15d0: 70 65 20 70 6c 61 79 73 20 74 68 65 20 6c 61 72  pe plays the lar
15e0: 67 65 73 74 20 72 6f 6c 65 20 69 6e 20 74 68 65  gest role in the
15f0: 20 63 6f 73 74 2e 20 48 65 72 65 20 61 72 65 20   cost. Here are 
1600: 73 6f 6d 65 20 61 70 70 72 6f 78 69 6d 61 74 65  some approximate
1610: 20 52 41 4d 20 6d 65 6d 6f 72 79 20 75 73 61 67   RAM memory usag
1620: 65 73 20 28 61 73 20 6d 65 61 73 75 72 65 64 20  es (as measured 
1630: 62 79 20 76 61 6c 67 72 69 6e 64 29 20 66 6f 72  by valgrind) for
1640: 20 61 20 64 65 6d 6f 2f 74 65 73 74 20 61 70 70   a demo/test app
1650: 6c 69 63 61 74 69 6f 6e 20 6f 6e 20 61 20 33 32  lication on a 32
1660: 2d 62 69 74 20 73 79 73 74 65 6d 2e 2e 2e 0d 0a  -bit system.....
1670: 0d 0a 20 20 20 2a 20 20 46 69 6c 65 2d 62 61 73  ..   *  File-bas
1680: 65 64 3a 20 31 35 6b 62 20 28 6d 6f 73 74 20 6f  ed: 15kb (most o
1690: 66 20 74 68 69 73 20 77 61 73 20 75 6e 72 65 6c  f this was unrel
16a0: 61 74 65 64 20 74 6f 20 73 65 73 73 69 6f 6e 20  ated to session 
16b0: 6d 61 6e 61 67 65 6d 65 6e 74 29 0d 0a 20 20 20  management)..   
16c0: 2a 20 20 68 61 73 68 74 61 62 6c 65 2d 62 61 73  *  hashtable-bas
16d0: 65 64 3a 20 31 39 6b 62 0d 0a 20 20 20 2a 20 20  ed: 19kb..   *  
16e0: 73 71 6c 69 74 65 33 3a 20 31 30 35 6b 62 0d 0a  sqlite3: 105kb..
16f0: 20 20 20 2a 20 20 6d 79 73 71 6c 35 3a 20 32 32     *  mysql5: 22
1700: 32 6b 62 0d 0a 0d 0a 28 45 61 63 68 20 6f 66 20  2kb....(Each of 
1710: 74 68 6f 73 65 20 77 61 73 20 61 62 6f 75 74 20  those was about 
1720: 35 6b 62 20 62 69 67 67 65 72 20 6f 6e 20 36 34  5kb bigger on 64
1730: 2d 62 69 74 20 62 75 69 6c 64 2e 29 0d 0a 0d 0a  -bit build.)....
1740: 46 6f 72 20 74 68 65 20 66 69 6c 65 2d 20 61 6e  For the file- an
1750: 64 20 68 61 73 68 74 61 62 6c 65 2d 62 61 73 65  d hashtable-base
1760: 64 20 6d 61 6e 61 67 65 72 73 2c 20 66 61 72 20  d managers, far 
1770: 6c 65 73 73 20 74 68 61 6e 20 31 6b 62 20 77 61  less than 1kb wa
1780: 73 20 74 68 65 20 61 63 74 75 61 6c 20 73 65 73  s the actual ses
1790: 73 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 2c  sion management,
17a0: 20 61 6e 6f 74 68 65 72 20 31 6b 62 20 6f 72 20   another 1kb or 
17b0: 73 6f 20 77 65 72 65 20 74 68 65 20 73 65 73 73  so were the sess
17c0: 69 6f 6e 20 64 61 74 61 2c 20 61 6e 64 20 74 68  ion data, and th
17d0: 65 20 72 65 6d 61 69 6e 69 6e 67 20 31 33 6b 62  e remaining 13kb
17e0: 20 28 6f 72 20 73 6f 29 20 77 61 73 20 61 70 70   (or so) was app
17f0: 6c 69 63 61 74 69 6f 6e 20 73 74 61 74 65 20 75  lication state u
1800: 6e 72 65 6c 61 74 65 64 20 74 6f 20 73 65 73 73  nrelated to sess
1810: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 2e 20  ion management. 
1820: 54 68 75 73 20 77 65 20 63 61 6e 2c 20 66 6f 72  Thus we can, for
1830: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 65   purposes of the
1840: 20 73 71 6c 69 74 65 33 2f 6d 79 73 71 6c 20 76   sqlite3/mysql v
1850: 61 6c 75 65 73 2c 20 64 65 72 69 76 65 20 74 68  alues, derive th
1860: 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 73 65  e approximate se
1870: 73 73 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ssion management
1880: 20 63 6f 73 74 73 20 62 79 20 73 75 62 74 72 61   costs by subtra
1890: 63 74 69 6e 67 20 31 33 6b 62 20 66 72 6f 6d 20  cting 13kb from 
18a0: 74 68 65 69 72 20 76 61 6c 75 65 73 2e 20 54 68  their values. Th
18b0: 69 73 20 63 6f 73 74 73 20 77 69 6c 6c 20 6f 66  is costs will of
18c0: 20 63 6f 75 72 73 65 20 64 69 66 66 65 72 20 64   course differ d
18d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
18e0: 73 69 7a 65 20 6f 66 20 74 68 65 20 61 70 70 6c  size of the appl
18f0: 69 63 61 74 69 6f 6e 27 73 20 64 61 74 61 20 73  ication's data s
1900: 65 74 2e 0d 0a 0d 0a 53 74 6f 72 61 67 65 20 63  et.....Storage c
1910: 6f 73 74 73 20 61 72 65 20 6f 66 20 63 6f 75 72  osts are of cour
1920: 73 65 20 64 69 72 65 63 74 6c 79 20 72 65 6c 61  se directly rela
1930: 74 65 64 20 74 6f 20 74 68 65 20 73 69 7a 65 20  ted to the size 
1940: 6f 66 20 74 68 65 20 73 65 73 73 69 6f 6e 20 64  of the session d
1950: 61 74 61 2c 20 70 6c 75 73 20 61 6e 79 20 6f 76  ata, plus any ov
1960: 65 72 68 65 61 64 20 69 6d 70 6f 73 65 64 20 62  erhead imposed b
1970: 79 20 74 68 65 20 63 6f 6e 63 72 65 74 65 20 73  y the concrete s
1980: 65 73 73 69 6f 6e 20 6d 61 6e 61 67 65 72 20 69  ession manager i
1990: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 53  mplementation. S
19a0: 65 73 73 69 6f 6e 20 4a 53 4f 4e 20 64 61 74 61  ession JSON data
19b0: 20 69 73 20 73 74 6f 72 65 64 20 77 69 74 68 6f   is stored witho
19c0: 75 74 20 61 6e 79 20 65 78 74 72 61 20 73 70 61  ut any extra spa
19d0: 63 69 6e 67 20 66 6f 72 20 68 75 6d 61 6e 2d 72  cing for human-r
19e0: 65 61 64 61 62 69 6c 69 74 79 2c 20 74 6f 20 73  eadability, to s
19f0: 61 76 65 20 6f 6e 20 73 74 6f 72 61 67 65 20 73  ave on storage s
1a00: 70 61 63 65 2e 20 53 6f 6d 65 20 6d 61 6e 61 67  pace. Some manag
1a10: 65 72 73 2c 20 6c 69 6b 65 20 74 68 65 20 68 61  ers, like the ha
1a20: 73 68 74 61 62 6c 65 2d 20 6f 72 20 63 70 64 6f  shtable- or cpdo
1a30: 2d 62 61 73 65 64 20 6d 61 6e 61 67 65 72 73 2c  -based managers,
1a40: 20 68 61 76 65 20 74 6f 20 62 75 66 66 65 72 20   have to buffer 
1a50: 74 68 65 69 72 20 4a 53 4f 4e 20 69 6e 70 75 74  their JSON input
1a60: 2f 6f 75 74 70 75 74 20 69 6e 74 6f 20 52 41 4d  /output into RAM
1a70: 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
1a80: 65 20 70 72 6f 63 65 73 73 65 64 20 6f 72 20 77  e processed or w
1a90: 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20 73 74  ritten to the st
1aa0: 6f 72 61 67 65 2c 20 77 68 65 72 65 61 73 20 6f  orage, whereas o
1ab0: 74 68 65 72 73 2c 20 6e 61 6d 65 6c 79 20 74 68  thers, namely th
1ac0: 65 20 66 69 6c 65 2d 62 61 73 65 64 20 6d 61 6e  e file-based man
1ad0: 61 67 65 72 2c 20 63 61 6e 20 73 74 72 65 61 6d  ager, can stream
1ae0: 20 74 68 65 20 64 61 74 61 20 64 69 72 65 63 74   the data direct
1af0: 6c 79 20 74 68 72 6f 75 67 68 20 3c 74 74 3e 63  ly through <tt>c
1b00: 73 6f 6e 5f 70 61 72 73 65 28 29 3c 2f 74 74 3e  son_parse()</tt>
1b10: 20 61 6e 64 20 3c 74 74 3e 63 73 6f 6e 5f 6f 75   and <tt>cson_ou
1b20: 74 70 75 74 28 29 3c 2f 74 74 3e 20 77 69 74 68  tput()</tt> with
1b30: 6f 75 74 20 61 6e 20 69 6e 74 65 72 6d 65 64 69  out an intermedi
1b40: 61 72 79 20 62 75 66 66 65 72 2e 0d 0a 0d 0a 69  ary buffer.....i
1b50: 20 6d 61 79 20 73 6f 6d 65 64 61 79 20 61 64 64   may someday add
1b60: 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 6f 20 63   the option to c
1b70: 6f 6d 70 72 65 73 73 20 74 68 65 20 73 65 73 73  ompress the sess
1b80: 69 6f 6e 20 64 61 74 61 2c 20 62 75 74 20 74 68  ion data, but th
1b90: 61 74 20 77 6f 75 6c 64 20 72 65 71 75 69 72 65  at would require
1ba0: 20 63 6f 6d 70 72 65 73 73 69 6e 67 20 74 68 65   compressing the
1bb0: 20 63 6f 6e 74 65 6e 74 73 20 65 6e 74 69 72 65   contents entire
1bc0: 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 20 62 65 63  ly in memory bec
1bd0: 61 75 73 65 20 77 65 20 63 61 6e 6e 6f 74 20 67  ause we cannot g
1be0: 65 6e 65 72 69 63 61 6c 6c 79 20 73 74 72 65 61  enerically strea
1bf0: 6d 20 74 68 65 20 64 61 74 61 20 74 6f 2f 66 72  m the data to/fr
1c00: 6f 6d 20 74 68 65 20 62 61 63 6b 65 6e 64 2e 20  om the backend. 
1c10: 65 2e 67 2e 20 77 65 20 63 61 6e 6e 6f 74 20 73  e.g. we cannot s
1c20: 74 72 65 61 6d 20 63 6f 6c 75 6d 6e 20 64 61 74  tream column dat
1c30: 61 20 74 6f 20 61 20 64 61 74 61 62 61 73 65 20  a to a database 
1c40: 74 68 69 73 20 77 61 79 2c 20 73 6f 20 77 65 20  this way, so we 
1c50: 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 63 6f  would have to co
1c60: 6d 70 72 65 73 73 20 69 74 20 69 6e 20 6d 65 6d  mpress it in mem
1c70: 6f 72 79 20 66 69 72 73 74 20 61 6e 64 20 74 68  ory first and th
1c80: 65 6e 20 77 72 69 74 65 20 74 68 65 20 63 6f 6d  en write the com
1c90: 70 72 65 73 73 65 64 20 64 61 74 61 20 61 73 20  pressed data as 
1ca0: 61 20 42 4c 4f 42 20 28 77 68 69 63 68 20 69 73  a BLOB (which is
1cb0: 20 6e 6f 74 20 69 6e 68 65 72 65 6e 74 6c 79 20   not inherently 
1cc0: 77 72 6f 6e 67 2c 20 62 79 20 74 68 65 20 77 61  wrong, by the wa
1cd0: 79 29 2e 20 4c 69 6b 65 77 69 73 65 20 66 6f 72  y). Likewise for
1ce0: 20 72 65 61 64 69 6e 67 2e 20 57 68 61 74 20 69   reading. What i
1cf0: 27 6d 20 74 72 79 69 6e 67 20 74 6f 20 73 61 79  'm trying to say
1d00: 20 69 73 20 74 68 61 74 20 74 68 65 20 6c 6f 61   is that the loa
1d10: 64 2f 73 61 76 65 2d 72 65 6c 61 74 65 64 20 6d  d/save-related m
1d20: 65 6d 6f 72 79 20 63 6f 73 74 73 20 77 6f 75 6c  emory costs woul
1d30: 64 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  d approximately 
1d40: 64 6f 75 62 6c 65 20 64 75 65 20 74 6f 20 74 68  double due to th
1d50: 65 20 72 65 71 75 69 72 65 6d 65 6e 74 20 6f 66  e requirement of
1d60: 20 62 75 66 66 65 72 69 6e 67 20 74 68 65 20 64   buffering the d
1d70: 65 2f 63 6f 6d 70 72 65 73 73 65 64 20 64 61 74  e/compressed dat
1d80: 61 2e 20 41 6e 64 2c 20 67 69 76 65 6e 20 74 68  a. And, given th
1d90: 65 20 28 61 6e 74 69 63 69 70 61 74 65 64 29 20  e (anticipated) 
1da0: 61 76 65 72 61 67 65 20 73 69 7a 65 20 6f 66 20  average size of 
1db0: 73 65 73 73 69 6f 6e 20 64 61 74 61 20 28 61 20  session data (a 
1dc0: 66 65 77 20 6b 62 20 6f 72 20 6c 65 73 73 29 2c  few kb or less),
1dd0: 20 74 68 65 20 64 65 2f 63 6f 6d 70 72 65 73 73   the de/compress
1de0: 69 6f 6e 2d 72 65 6c 61 74 65 64 20 62 75 66 66  ion-related buff
1df0: 65 72 69 6e 67 20 61 6e 64 20 6f 76 65 72 68 65  ering and overhe
1e00: 61 64 20 69 73 20 6c 69 6b 65 6c 79 20 74 6f 20  ad is likely to 
1e10: 73 77 61 6d 70 20 61 6e 79 20 73 74 6f 72 61 67  swamp any storag
1e20: 65 20 67 61 69 6e 73 2e 0d 0a 0d 0a 0d 0a 3c 68  e gains.......<h
1e30: 31 3e 49 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 43  1>Implementing C
1e40: 75 73 74 6f 6d 20 42 61 63 6b 2d 65 6e 64 73 3c  ustom Back-ends<
1e50: 2f 68 31 3e 0d 0a 0d 0a 54 68 65 20 6c 69 62 72  /h1>....The libr
1e60: 61 72 79 20 6f 6e 6c 79 20 73 70 65 63 69 66 69  ary only specifi
1e70: 65 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  es a generic int
1e80: 65 72 66 61 63 65 2c 20 61 6e 64 20 6e 6f 74 20  erface, and not 
1e90: 68 6f 77 20 69 74 20 69 73 20 74 6f 20 62 65 20  how it is to be 
1ea0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 49 74 20  implemented. It 
1eb0: 61 6c 73 6f 20 63 6f 6d 65 73 20 77 69 74 68 20  also comes with 
1ec0: 74 77 6f 20 76 65 72 79 20 64 69 66 66 65 72 65  two very differe
1ed0: 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1ee0: 6e 73 2c 20 62 75 74 20 74 68 61 74 27 73 20 6d  ns, but that's m
1ef0: 61 69 6e 6c 79 20 74 6f 20 73 68 6f 77 20 74 68  ainly to show th
1f00: 61 74 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  at the interface
1f10: 20 69 74 73 65 6c 66 20 69 73 20 73 75 69 74 65   itself is suite
1f20: 64 20 74 6f 20 69 74 73 20 70 75 72 70 6f 73 65  d to its purpose
1f30: 20 28 69 74 20 77 61 73 20 64 65 73 69 67 6e 65   (it was designe
1f40: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 5b 63 73  d to support [cs
1f50: 6f 6e 5f 63 67 69 5d 29 2e 20 54 68 65 20 69 6d  on_cgi]). The im
1f60: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 74 68 61  plication is tha
1f70: 74 20 63 6c 69 65 6e 74 73 20 63 61 6e 20 70 72  t clients can pr
1f80: 6f 76 69 64 65 20 63 6f 6e 63 72 65 74 65 20 69  ovide concrete i
1f90: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
1fa0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
1fb0: 65 73 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68  es to provide th
1fc0: 65 69 72 20 6f 77 6e 20 73 74 6f 72 61 67 65 20  eir own storage 
1fd0: 62 61 63 6b 2d 65 6e 64 73 20 28 65 2e 67 2e 20  back-ends (e.g. 
1fe0: 61 6e 20 6f 6e 2d 64 69 73 6b 20 68 61 73 68 74  an on-disk hasht
1ff0: 61 62 6c 65 20 6f 72 20 61 6e 20 5b 68 74 74 70  able or an [http
2000: 3a 2f 2f 66 6f 73 73 69 6c 2e 77 61 6e 64 65 72  ://fossil.wander
2010: 69 6e 67 68 6f 72 73 65 2e 6e 65 74 2f 72 65 70  inghorse.net/rep
2020: 6f 73 2f 77 68 69 6f 2f 69 6e 64 65 78 2e 63 67  os/whio/index.cg
2030: 69 2f 77 69 6b 69 2f 77 68 69 6f 5f 65 70 66 73  i/wiki/whio_epfs
2040: 7c 65 6d 62 65 64 64 65 64 20 66 69 6c 65 73 79  |embedded filesy
2050: 73 74 65 6d 5d 29 2e 0d 0a 0d 0a 54 68 65 20 3c  stem]).....The <
2060: 74 74 3e 63 73 6f 6e 5f 73 65 73 73 6d 67 72 3c  tt>cson_sessmgr<
2070: 2f 74 74 3e 20 69 6e 74 65 72 66 61 63 65 2c 20  /tt> interface, 
2080: 70 72 65 73 65 6e 74 65 64 20 69 6e 20 3c 74 74  presented in <tt
2090: 3e 63 73 6f 6e 5f 73 65 73 73 69 6f 6e 2e 68 3c  >cson_session.h<
20a0: 2f 74 74 3e 2c 20 64 65 63 6c 61 72 65 73 20 6f  /tt>, declares o
20b0: 6e 6c 79 20 66 6f 75 72 20 6f 70 65 72 61 74 69  nly four operati
20c0: 6f 6e 73 20 66 6f 72 20 73 65 73 73 69 6f 6e 20  ons for session 
20d0: 6d 61 6e 61 67 65 6d 65 6e 74 2e 20 54 68 6f 73  management. Thos
20e0: 65 20 61 72 65 2c 20 69 6e 20 63 6f 6e 63 65 70  e are, in concep
20f0: 74 75 61 6c 20 74 65 72 6d 73 20 28 74 68 65 20  tual terms (the 
2100: 73 69 67 6e 61 74 75 72 65 73 20 61 63 74 75 61  signatures actua
2110: 6c 6c 79 20 6c 6f 6f 6b 20 61 20 62 69 74 20 64  lly look a bit d
2120: 69 66 66 65 72 65 6e 74 2c 20 61 6e 64 20 61 72  ifferent, and ar
2130: 65 20 73 69 6d 70 6c 69 66 69 65 64 20 68 65 72  e simplified her
2140: 65 20 66 6f 72 20 63 6c 61 72 69 74 79 29 3a 0d  e for clarity):.
2150: 0a 0d 0a 20 20 20 2a 20 20 3c 74 74 3e 63 73 6f  ...   *  <tt>cso
2160: 6e 5f 76 61 6c 75 65 20 2a 20 6c 6f 61 64 28 20  n_value * load( 
2170: 63 68 61 72 20 63 6f 6e 73 74 20 2a 20 73 65 73  char const * ses
2180: 73 69 6f 6e 5f 49 44 20 29 3c 2f 74 74 3e 20 6c  sion_ID )</tt> l
2190: 6f 61 64 73 20 61 20 4a 53 4f 4e 20 6f 62 6a 65  oads a JSON obje
21a0: 63 74 2f 61 72 72 61 79 20 74 72 65 65 20 62 79  ct/array tree by
21b0: 20 73 65 73 73 69 6f 6e 20 49 44 2e 0d 0a 20 20   session ID...  
21c0: 20 2a 20 20 3c 74 74 3e 69 6e 74 20 73 61 76 65   *  <tt>int save
21d0: 28 20 63 73 6f 6e 5f 76 61 6c 75 65 20 2a 20 6a  ( cson_value * j
21e0: 73 6f 6e 2c 20 63 68 61 72 20 63 6f 6e 73 74 20  son, char const 
21f0: 2a 20 73 65 73 73 69 6f 6e 5f 49 44 20 29 3c 2f  * session_ID )</
2200: 74 74 3e 20 73 61 76 65 73 20 61 20 4a 53 4f 4e  tt> saves a JSON
2210: 20 6f 62 6a 65 63 74 2f 61 72 72 61 79 20 74 72   object/array tr
2220: 65 65 20 75 73 69 6e 67 20 74 68 65 20 67 69 76  ee using the giv
2230: 65 6e 20 73 65 73 73 69 6f 6e 20 49 44 2e 0d 0a  en session ID...
2240: 20 20 20 2a 20 20 3c 74 74 3e 69 6e 74 20 72 65     *  <tt>int re
2250: 6d 6f 76 65 28 20 63 68 61 72 20 63 6f 6e 73 74  move( char const
2260: 20 2a 20 73 65 73 73 69 6f 6e 5f 49 44 20 29 3c   * session_ID )<
2270: 2f 74 74 3e 20 72 65 6d 6f 76 65 73 20 74 68 65  /tt> removes the
2280: 20 67 69 76 65 6e 20 49 44 20 66 72 6f 6d 20 74   given ID from t
2290: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 74  he underlying st
22a0: 6f 72 61 67 65 2e 0d 0a 20 20 20 2a 20 20 3c 74  orage...   *  <t
22b0: 74 3e 76 6f 69 64 20 66 69 6e 61 6c 69 7a 65 28  t>void finalize(
22c0: 29 3c 2f 74 74 3e 20 63 6c 65 61 6e 73 20 75 70  )</tt> cleans up
22d0: 20 74 68 65 20 73 65 73 73 69 6f 6e 20 6d 61 6e   the session man
22e0: 61 67 65 72 20 69 6e 73 74 61 6e 63 65 2c 20 69  ager instance, i
22f0: 6e 63 6c 75 64 69 6e 67 20 61 6e 79 20 72 65 73  ncluding any res
2300: 6f 75 72 63 65 73 20 69 74 20 6f 77 6e 73 20 28  ources it owns (
2310: 65 2e 67 2e 20 61 20 64 61 74 61 62 61 73 65 20  e.g. a database 
2320: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
2330: 65 29 2e 0d 0a 0d 0a 49 6d 70 6c 65 6d 65 6e 74  e).....Implement
2340: 69 6e 67 20 63 75 73 74 6f 6d 20 6f 6e 65 73 20  ing custom ones 
2350: 69 73 20 73 69 6d 70 6c 65 2e 20 41 73 20 61 20  is simple. As a 
2360: 62 65 6e 63 68 6d 61 72 6b 2c 20 74 68 65 20 66  benchmark, the f
2370: 69 6c 65 2d 20 61 6e 64 20 63 70 64 6f 2d 62 61  ile- and cpdo-ba
2380: 73 65 64 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  sed implementati
2390: 6f 6e 73 20 65 61 63 68 20 74 6f 6f 6b 20 75 6e  ons each took un
23a0: 64 65 72 20 74 77 6f 20 68 6f 75 72 73 20 74 6f  der two hours to
23b0: 20 69 6d 70 6c 65 6d 65 6e 74 2c 20 61 6e 64 20   implement, and 
23c0: 6d 75 63 68 20 6f 66 20 74 68 61 74 20 74 69 6d  much of that tim
23d0: 65 20 77 61 73 20 64 75 65 20 74 6f 20 6d 65 20  e was due to me 
23e0: 63 68 61 6e 67 69 6e 67 20 74 68 65 20 41 50 49  changing the API
23f0: 20 61 6e 64 20 63 6f 6e 66 69 67 75 72 61 74 69   and configurati
2400: 6f 6e 2d 72 65 6c 61 74 65 64 20 69 6e 74 65 72  on-related inter
2410: 66 61 63 65 73 20 73 65 76 65 72 61 6c 20 74 69  faces several ti
2420: 6d 65 73 20 64 75 72 69 6e 67 20 64 65 76 65 6c  mes during devel
2430: 6f 70 6d 65 6e 74 2e 20 49 66 20 6f 6e 65 20 77  opment. If one w
2440: 65 72 65 20 74 6f 20 73 69 74 20 64 6f 77 6e 20  ere to sit down 
2450: 61 20 77 72 69 74 65 20 61 20 63 75 73 74 6f 6d  a write a custom
2460: 20 66 69 6c 65 2d 62 61 73 65 64 20 69 6d 70 6c   file-based impl
2470: 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f  ementation witho
2480: 75 74 20 74 68 65 20 22 64 65 76 65 6c 6f 70 6d  ut the "developm
2490: 65 6e 74 20 6d 6f 64 65 22 20 6f 76 65 72 68 65  ent mode" overhe
24a0: 61 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  ad of the first 
24b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
24c0: 20 69 74 20 63 6f 75 6c 64 20 70 72 6f 62 61 62   it could probab
24d0: 6c 79 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74 65  ly be implemente
24e0: 64 20 69 6e 20 75 6e 64 65 72 20 61 6e 20 68 6f  d in under an ho
24f0: 75 72 20 6f 66 20 77 6f 72 6b 2c 20 70 72 6f 76  ur of work, prov
2500: 69 64 65 64 20 74 68 65 20 75 6e 64 65 72 6c 79  ided the underly
2510: 69 6e 67 20 6c 69 62 72 61 72 79 20 63 61 6e 20  ing library can 
2520: 64 6f 20 77 68 61 74 20 6e 65 65 64 73 20 74 6f  do what needs to
2530: 20 62 65 20 64 6f 6e 65 20 77 69 74 68 6f 75 74   be done without
2540: 20 6d 75 63 68 20 73 68 6f 65 68 6f 72 6e 69 6e   much shoehornin
2550: 67 2e 0d 0a 0d 0a 53 65 65 20 74 68 65 20 66 69  g.....See the fi
2560: 6c 65 73 20 3c 74 74 3e 63 73 6f 6e 5f 73 65 73  les <tt>cson_ses
2570: 73 69 6f 6e 5f 66 69 6c 65 2e 63 3c 2f 74 74 3e  sion_file.c</tt>
2580: 20 61 6e 64 20 3c 74 74 3e 63 73 6f 6e 5f 73 65   and <tt>cson_se
2590: 73 73 69 6f 6e 5f 63 70 64 6f 2e 63 3c 2f 74 74  ssion_cpdo.c</tt
25a0: 3e 20 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6d  > for example im
25b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 20 54  plementations. T
25c0: 68 65 20 66 69 6c 65 2d 62 61 73 65 64 20 69 6d  he file-based im
25d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 75 72  plementation cur
25e0: 72 65 6e 74 6c 79 20 28 32 30 31 31 30 34 31 31  rently (20110411
25f0: 29 20 68 61 73 20 6f 6e 6c 79 20 61 62 6f 75 74  ) has only about
2600: 20 31 37 30 20 72 65 61 6c 20 6c 69 6e 65 73 20   170 real lines 
2610: 6f 66 20 63 6f 64 65 20 61 6e 64 20 74 68 65 20  of code and the 
2620: 64 61 74 61 62 61 73 65 20 69 6d 70 6c 65 6d 65  database impleme
2630: 6e 74 61 74 69 6f 6e 20 68 61 73 20 61 62 6f 75  ntation has abou
2640: 74 20 32 38 30 2e 0d 0a 0d 0a 4f 6e 63 65 20 61  t 280.....Once a
2650: 20 63 75 73 74 6f 6d 20 6d 61 6e 61 67 65 72 20   custom manager 
2660: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69  is implemented i
2670: 74 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  t can be registe
2680: 72 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  red for use with
2690: 20 6f 74 68 65 72 20 73 65 73 73 69 6f 6e 2d 75   other session-u
26a0: 73 69 6e 67 20 63 6f 64 65 20 62 79 20 63 61 6c  sing code by cal
26b0: 6c 69 6e 67 20 3c 74 74 3e 63 73 6f 6e 5f 73 65  ling <tt>cson_se
26c0: 73 73 6d 67 72 5f 72 65 67 69 73 74 65 72 28 29  ssmgr_register()
26d0: 3c 2f 74 74 3e 2c 20 61 6e 64 20 63 6c 69 65 6e  </tt>, and clien
26e0: 74 73 20 63 61 6e 20 69 6e 73 74 61 6e 74 69 61  ts can instantia
26f0: 74 65 20 61 20 72 65 67 69 73 74 65 72 65 64 20  te a registered 
2700: 73 65 73 73 69 6f 6e 20 6d 61 6e 61 67 65 72 20  session manager 
2710: 62 79 20 6e 61 6d 65 20 75 73 69 6e 67 20 3c 74  by name using <t
2720: 74 3e 63 73 6f 6e 5f 73 65 73 73 6d 67 72 5f 6c  t>cson_sessmgr_l
2730: 6f 61 64 28 29 3c 2f 74 74 3e 2e 0d 0a 0d 0a 0d  oad()</tt>......
2740: 0a 3c 68 31 3e 54 4f 44 4f 73 3c 2f 68 31 3e 0d  .<h1>TODOs</h1>.
2750: 0a 0d 0a 3c 73 74 72 6f 6e 67 3e 4e 6f 74 61 62  ...<strong>Notab
2760: 6c 65 20 54 4f 44 4f 73 2e 2e 2e 3c 2f 73 74 72  le TODOs...</str
2770: 6f 6e 67 3e 0d 0a 0d 0a 20 20 20 2a 20 20 41 6e  ong>....   *  An
2780: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2790: 77 68 69 63 68 20 75 73 65 73 20 48 54 54 50 20  which uses HTTP 
27a0: 63 6f 6f 6b 69 65 73 20 66 6f 72 20 73 74 6f 72  cookies for stor
27b0: 61 67 65 2e 20 54 68 61 74 20 72 65 71 75 69 72  age. That requir
27c0: 65 73 20 74 68 61 74 20 69 20 66 69 72 73 74 20  es that i first 
27d0: 61 64 64 20 4f 62 6a 65 63 74 2f 41 72 72 61 79  add Object/Array
27e0: 20 73 75 70 70 6f 72 74 20 74 6f 20 74 68 65 20   support to the 
27f0: 63 6f 6f 6b 69 65 20 73 65 72 69 61 6c 69 7a 61  cookie serializa
2800: 74 69 6f 6e 20 62 69 74 73 2e 20 49 6e 20 61 6e  tion bits. In an
2810: 64 20 6f 66 20 69 74 73 65 6c 66 2c 20 74 68 61  d of itself, tha
2820: 74 27 73 20 65 61 73 79 20 65 6e 6f 75 67 68 20  t's easy enough 
2830: 74 6f 20 64 6f 2c 20 62 75 74 20 3c 65 6d 3e 73  to do, but <em>s
2840: 6f 6d 65 3c 2f 65 6d 3e 20 63 6f 6f 6b 69 65 73  ome</em> cookies
2850: 20 61 72 65 20 74 68 65 6d 73 65 6c 76 65 73 20   are themselves 
2860: 73 74 6f 72 65 64 20 61 73 20 6f 62 6a 65 63 74  stored as object
2870: 73 2c 20 73 6f 20 77 65 20 68 61 76 65 20 61 6e  s, so we have an
2880: 20 61 6d 62 69 67 75 69 74 79 20 70 72 6f 62 6c   ambiguity probl
2890: 65 6d 2e 20 49 66 20 69 20 61 64 64 20 74 68 65  em. If i add the
28a0: 20 61 62 69 6c 69 74 79 20 74 6f 20 61 64 64 20   ability to add 
28b0: 63 6c 69 65 6e 74 2d 73 70 65 63 69 66 69 63 20  client-specific 
28c0: 66 6c 61 67 73 20 74 6f 20 3c 74 74 3e 63 73 6f  flags to <tt>cso
28d0: 6e 5f 6f 62 6a 65 63 74 3c 2f 74 74 3e 2c 20 69  n_object</tt>, i
28e0: 20 63 6f 75 6c 64 20 77 6f 72 6b 20 61 72 6f 75   could work arou
28f0: 6e 64 20 69 74 2c 20 62 75 74 20 74 68 61 74 20  nd it, but that 
2900: 77 6f 75 6c 64 20 62 65 20 6b 6c 75 64 67 79 2e  would be kludgy.
2910: 20 69 27 64 20 66 75 6e 64 61 6d 65 6e 74 61 6c   i'd fundamental
2920: 6c 79 20 6c 69 6b 65 20 74 6f 20 68 61 76 65 20  ly like to have 
2930: 63 6c 69 65 6e 74 2d 73 70 65 63 69 66 69 65 64  client-specified
2940: 20 66 6c 61 67 73 20 66 6f 72 20 61 6c 6c 20 3c   flags for all <
2950: 74 74 3e 63 73 6f 6e 5f 76 61 6c 75 65 3c 2f 74  tt>cson_value</t
2960: 74 3e 20 69 6e 73 74 61 6e 63 65 73 2c 20 62 75  t> instances, bu
2970: 74 20 69 27 6d 20 6e 6f 74 20 6b 65 65 6e 20 6f  t i'm not keen o
2980: 6e 20 61 64 64 69 6e 67 20 74 68 61 74 20 74 6f  n adding that to
2990: 20 74 68 65 69 72 20 6d 65 6d 6f 72 79 20 63 6f   their memory co
29a0: 73 74 20 61 6e 64 20 69 74 20 77 6f 75 6c 64 20  st and it would 
29b0: 69 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 74  interfere with t
29c0: 68 65 20 22 73 70 65 63 69 61 6c 22 20 69 6e 74  he "special" int
29d0: 65 72 6e 61 6c 20 63 6f 6e 73 74 61 6e 74 20 76  ernal constant v
29e0: 61 6c 75 65 73 20 6c 69 6b 65 20 65 6d 70 74 79  alues like empty
29f0: 20 73 74 72 69 6e 67 73 2c 20 62 6f 6f 6c 65 61   strings, boolea
2a00: 6e 73 2c 20 6e 75 6c 6c 2c 20 61 6e 64 20 74 68  ns, null, and th
2a10: 65 20 6e 75 6d 62 65 72 20 30 2e 0d 0a 0d 0a 3c  e number 0.....<
2a20: 73 74 72 6f 6e 67 3e 4c 65 73 73 20 70 72 65 73  strong>Less pres
2a30: 73 69 6e 67 20 54 4f 44 4f 73 2e 2e 2e 3c 2f 73  sing TODOs...</s
2a40: 74 72 6f 6e 67 3e 0d 0a 0d 0a 20 20 20 2a 20 20  trong>....   *  
2a50: 53 74 61 6e 64 61 72 64 69 7a 65 20 74 68 65 20  Standardize the 
2a60: 6c 61 73 74 2d 73 61 76 65 64 20 74 69 6d 65 73  last-saved times
2a70: 74 61 6d 70 73 20 74 6f 20 47 4d 54 2f 55 54 43  tamps to GMT/UTC
2a80: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
2a90: 63 75 72 72 65 6e 74 20 75 73 65 20 6f 66 20 6c  current use of l
2aa0: 6f 63 61 6c 20 74 69 6d 65 2e 0a 0a 5a 20 64 37  ocal time...Z d7
2ab0: 35 65 65 35 33 37 66 64 64 62 30 33 66 62 66 33  5ee537fddb03fbf3
2ac0: 65 34 39 66 38 61 32 65 61 34 65 31 62 65 0a     e49f8a2ea4e1be.