{"id":26052668,"url":"https://github.com/robtweed/ewd-session","last_synced_at":"2025-04-10T23:32:22.643Z","repository":{"id":138539613,"uuid":"53416226","full_name":"robtweed/ewd-session","owner":"robtweed","description":"Session management using ewd-document-store DocumentNodes","archived":false,"fork":false,"pushed_at":"2021-02-15T16:40:10.000Z","size":75,"stargazers_count":4,"open_issues_count":5,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T19:09:13.343Z","etag":null,"topics":["gtm","intersystems-cache","node-js","qewd","redis","session-management"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robtweed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-08T13:56:34.000Z","updated_at":"2025-01-30T13:24:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"50097a81-abb2-4b16-8230-19dabfb2078b","html_url":"https://github.com/robtweed/ewd-session","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robtweed%2Fewd-session","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robtweed%2Fewd-session/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robtweed%2Fewd-session/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robtweed%2Fewd-session/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robtweed","download_url":"https://codeload.github.com/robtweed/ewd-session/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247847610,"owners_count":21006100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gtm","intersystems-cache","node-js","qewd","redis","session-management"],"created_at":"2025-03-08T06:41:39.405Z","updated_at":"2025-04-10T23:32:22.609Z","avatar_url":"https://github.com/robtweed.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ewd-session: Session Management based on ewd-document-store DocumentNodes\n\n[![Build Status](https://travis-ci.org/robtweed/ewd-session.svg?branch=master)](https://travis-ci.org/robtweed/ewd-session) [![Coverage Status](https://coveralls.io/repos/github/robtweed/ewd-session/badge.svg?branch=master)](https://coveralls.io/github/robtweed/ewd-session?branch=master)\n\nRob Tweed \u003crtweed@mgateway.com\u003e  \n24 February 2016, M/Gateway Developments Ltd [http://www.mgateway.com](http://www.mgateway.com)  \n\nTwitter: [@rtweed](https://twitter.com/rtweed)\n\nGoogle Group for discussions, support, advice etc: [http://groups.google.co.uk/group/enterprise-web-developer-community](http://groups.google.co.uk/group/enterprise-web-developer-community)\n\n\n## ewd-session\n\nThis module may be used to provide session management. Sessions make use of the persistent JavaScript objects and fine-grained document database provided by ewd-document-store. For more information on ewd-document-store:\n\n[https://github.com/robtweed/ewd-document-store](https://github.com/robtweed/ewd-document-store)\n\nYou'll usually use ewd-session within an ewd-qoper8 worker process. For more informaation on ewd-qoper8:\n\n[https://github.com/robtweed/ewd-qoper8](https://github.com/robtweed/ewd-qoper8)\n\n\n## Installing\n\n       npm install ewd-session\n\n## Using ewd-session\n\nIf you are using ewd-session within an ewd-qoper8 worker process, you must first have connected the worker to a database that is supported by ewd-document-store, eg:\n\n- [InterSystems Cache](https://www.intersystems.com/products/cache/), using ewd-qoper8-cache: [https://github.com/robtweed/ewd-qoper8-cache](https://github.com/robtweed/ewd-qoper8-cache)\n- InterSystems GlobalsDB using ewd-qoper8-gtm [https://github.com/robtweed/ewd-qoper8-gtm](https://github.com/robtweed/ewd-qoper8-gtm)\n- GT.M (module not yet implemented)\n\nSpecifically, ewd-session expects the worker process to have instantiated a DocumentStore object, which is what these database-specific modules will have done when invoked within the worker's `start` event handler, eg:\n\n```js\nthis.on('start', function() {\n  var connectCacheTo = require('ewd-qoper8-cache');\n  connectCacheTo(this);\n  // this.documentStore provides access to the DocumentStore object\n});\n```\n\nIn order to create and use Sessions, you must load the ewd-session module into your ewd-qoper8 worker module:\n\n```js\nvar sessions = require('ewd-session');\n```\n\nThis provides you with the following constructors and methods:\n\n- __init__:               initialises the session module environment\n- __create__:             method for creating a new Session: returns a Session object (including Session.token - a unique token)\n- __authenticate__:       method for authenticating a Session Token and returning the corresponding Session object if valid\n- __garbageCollector__:   timer for use within a ewd-qoper8 worker process, for garbage-collecting expired Sessions\n- __uuid__:               method for generating a UUID\n- __symbolTable__         specialist method: creates methods for maintaining the connected MUMPS process's symbol table (aka local variables)\n\n### Initialising ewd-sessions\n\nYou must first initialise ewd-sessions.  This provides it with access to the DocumentStore object, eg:\n\n```js\nsessions.init(this.documentStore);\n```\n\nBy default, Sessions are maintained in a Document named `'%zewdSession'`. You can change this by using the _init()_ function's second argument, eg:\n\n```js\nsessions.init(this.documentStore, 'mySessionDocument');\n```\n\n### Session Garbage Collection\n\nIt is important to enable Session Garbage collection, otherwise your Document Store will accumulate expired session data.\n\nIf you are using ewd-qoper8, you should start an instance of the Session Garbage collector timer in your worker module. Do this within the worker's on('DocumentStoreStarted') handler:\n\n```js\nthis.on('DocumentStoreStarted', function() {\n  sessions.garbageCollector(this);\n});\n```\n\nBy default, every 5 minutes, this timer will check the Document Store for sessions and delete any expired ones.  You can adjust the checking frequency using the 2nd optional argument which specifies the delay time in seconds:\n\n```js\nsessions.garbageCollector(this, 1200); // check every 20 minutes\n```\n\n### Creating a New Session\n\nTo create a new Session:\n\n```js\nvar applicationName = 'vista';\nvar sessionTimeout = 300;  // in seconds; defaults to 3600 = 1 hour\nvar session = sessions.create(application, sessionTimeout);\n```\n\nYou'll be returned a Session object which provides access to the underlying DocumentNode storing the session's data.\n\nA Token Object will also have been created. This provides a pointer from the session's unique token to the Session.  You don't directly access the Token Object.\n\nNormally you'll send the Session token value (_session.token_) back to the client / browser.  It is used for subsequent, secure access to the Session the next time the user or client requires access to their Session.\n\n### The Session Object\n\n#### Properties\n\n- __exists__        (boolean; read only)\n- __token__         (string: read only) The unique token UUID that was created for this session\n- __expired__       (boolean: read only) Invoking this automatically deletes the Session from the Document Store if it was found to be expired\n- __authenticated__ (boolean: read/write) Set this to true when the user successfully logs in (if relevant)\n- __expiryTime__    (integer: read/write) The number of seconds before the Session will expire if inactive\n- __data__          (DocumentNode Object) Provides access to the Session's persistent data\n\n#### Methods\n\n- __delete()__  deletes the Session and its associated Token object.  Normally you can let sessions just expire naturally, so use of this method is usually unnecessary.\n\n### Accessing an Existing Session using a Token\n\nYou'll normally send a Session token as part of a message to your worker module.  In the case of Express HTTP requests, the token will normally be conveyed as the Authorization header value.  In WebSocket messages, you can allocate an appropriate message property to hold it.\n\nTo access the associated Session, use the authenticate method:\n\n```js\nvar results = sessions.authenticate(token);\n```\nWhere token is the value of the Session Token. Results is an object of the structure:\n\n     {\n       error: errorMessage,\n       session: SessionObject\n     }\n\n\nresults.session will contain the associated Session object if:\n\n- the token value was not null or a null string; and\n- the token was found in the Token Document in the Document Store; and\n- a corresponding Session Document was found in the Document Store; and\n- the corresponding Session had not expired\n\nOtherwise results.error will be defined and will be a string value that explains the reason why a Session object could not be returned.\n\nBy default, a successful invocation of the _sessions.authenticate()_ method will update the associated Session's expiry time.  In certain circumstances you might not want this to happen, for example if you want to log in the user.  In such a situation, if the login credentials aren't correct, you'll want to keep the clock ticking in terms of the remaining time you allow before the user can log in.\n\nIn such a situation, add true as a third argument:\n\n```js\nvar results = sessions.authenticate(token, true);\n```\n\n\n## Examples\n\nYou'll find two examples in the /examples path of this module repository:\n\n- cache-standalone.js: Standalone example using Cache that can be run as a script file\n- cache-express.js:    Example using Express, ewd-qoper8 and Cache. It will load cache-module1.js as the worker module. This allows you to invoke a GET request: `/qoper8/initiate` which starts a Session and returns a token.  You can then login using a POST request of `/qoper8/login` with a payload: `{\"username\": \"rob\", \"password\": \"secret\"}`\n\n\n## Integration tests\n\n  * You must have [InterSystem Caché](http://www.intersystems.com/our-products/cache/cache-overview/) installed.\n  * You must have `cache.node` in npm global registy. Read [Installation](http://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY=BXJS_intro#BXJS_intro_install) to get more details.\n  * Run `npm link cache.node` before running integration tests.\n  * You may need to run this as sudo because of permissions.\n\n\n## License\n\n Copyright (c) 2016 M/Gateway Developments Ltd,                           \n Reigate, Surrey UK.                                                      \n All rights reserved.                                                     \n                                                                           \n  http://www.mgateway.com                                                  \n  Email: rtweed@mgateway.com                                               \n                                                                           \n                                                                           \n  Licensed under the Apache License, Version 2.0 (the \"License\");          \n  you may not use this file except in compliance with the License.         \n  You may obtain a copy of the License at                                  \n                                                                           \n      http://www.apache.org/licenses/LICENSE-2.0                           \n                                                                           \n  Unless required by applicable law or agreed to in writing, software      \n  distributed under the License is distributed on an \"AS IS\" BASIS,        \n  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. \n  See the License for the specific language governing permissions and      \n   limitations under the License.      \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobtweed%2Fewd-session","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobtweed%2Fewd-session","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobtweed%2Fewd-session/lists"}