fix: infinite TTLs are not supported anymore, forward ttl=0 (#170)

* fix: infinite TTLs are not supported

* fix add doc hook

* fix e2e tests

* forward ttl=0 to server, but bring back e2e test checking that ttl=0 should default

Author: moritzraho

doc/api.md

@@ -6,15 +6,17 @@
 </dd>
 </dl>
 
-## Functions
+## Members
 
 <dl>
-<dt><a href="#validate">validate(schema, data)</a> ⇒ <code>object</code></dt>
-<dd><p>Validates json according to a schema.</p>
-</dd>
-<dt><a href="#handleResponse">handleResponse(response, params)</a> ⇒ <code>void</code></dt>
-<dd><p>Handle a network response.</p>
+<dt><a href="#MAX_TTL">MAX_TTL</a> : <code>number</code></dt>
+<dd><p>Max supported TTL, 365 days in seconds</p>
 </dd>
+</dl>
+
+## Functions
+
+<dl>
 <dt><a href="#init">init([config])</a> ⇒ <code><a href="#AdobeState">Promise.&lt;AdobeState&gt;</a></code></dt>
 <dd><p>Initializes and returns the key-value-store SDK.</p>
 <p>To use the SDK you must either provide your
@@ -159,31 +161,12 @@ for await (const { keys } of state.list({ match: 'abc*' })) {
    console.log(keys)
  }
 ```
-<a name="validate"></a>
-
-## validate(schema, data) ⇒ <code>object</code>
-Validates json according to a schema.
-
-**Kind**: global function  
-**Returns**: <code>object</code> - the result  
+<a name="MAX_TTL"></a>
 
-| Param | Type | Description |
-| --- | --- | --- |
-| schema | <code>object</code> | the AJV schema |
-| data | <code>object</code> | the json data to test |
-
-<a name="handleResponse"></a>
-
-## handleResponse(response, params) ⇒ <code>void</code>
-Handle a network response.
-
-**Kind**: global function  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| response | <code>Response</code> | a fetch Response |
-| params | <code>object</code> | the params to the network call |
+## MAX\_TTL : <code>number</code>
+Max supported TTL, 365 days in seconds
 
+**Kind**: global variable  
 <a name="init"></a>
 
 ## init([config]) ⇒ [<code>Promise.&lt;AdobeState&gt;</code>](#AdobeState)
@@ -227,7 +210,7 @@ AdobeState put options
 
 | Name | Type | Description |
 | --- | --- | --- |
-| ttl | <code>number</code> | time-to-live for key-value pair in seconds, defaults to 24 hours (86400s). Set to < 0 for max ttl of one year. A value of 0 sets default. |
+| ttl | <code>number</code> | Time-To-Live for key-value pair in seconds. When not   defined or set to 0, defaults to 24 hours (86400s). Max TTL is one year   (31536000s), `require('@adobe/aio-lib-state').MAX_TTL`. A TTL of 0 defaults   to 24 hours. |
 
 <a name="AdobeStateGetReturnValue"></a>
 

e2e/e2e.js

@@ -113,17 +113,20 @@ describe('e2e tests using OpenWhisk credentials (as env vars)', () => {
 
     // 3. test max ttl
     const nowPlus365Days = new Date(MAX_TTL_SECONDS).getTime()
-    expect(await state.put(testKey, testValue, { ttl: -1 })).toEqual(testKey)
+    expect(await state.put(testKey, testValue, { ttl: MAX_TTL_SECONDS })).toEqual(testKey)
     res = await state.get(testKey)
     resTime = new Date(res.expiration).getTime()
-    expect(resTime).toBeGreaterThanOrEqual(nowPlus365Days)
+    expect(resTime).toBeGreaterThanOrEqual(nowPlus365Days - 10000)
 
     // 4. test that after ttl object is deleted
     expect(await state.put(testKey, testValue, { ttl: 2 })).toEqual(testKey)
     res = await state.get(testKey)
     expect(new Date(res.expiration).getTime()).toBeLessThanOrEqual(new Date(Date.now() + 2000).getTime())
     await waitFor(3000) // give it one more sec - ttl is not so precise
     expect(await state.get(testKey)).toEqual(undefined)
+
+    // 5. infinite ttl not supported
+    await expect(state.put(testKey, testValue, { ttl: -1 })).rejects.toThrow()
   })
 
   test('listKeys test: few < 128 keys, many, and expired entries', async () => {

index.js

@@ -1,5 +1,5 @@
 /*
-Copyright 2019 Adobe. All rights reserved.
+Copyright 2024 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy
 of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -9,5 +9,13 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
+const { MAX_TTL_SECONDS } = require('./lib/constants')
 require('./lib/AdobeState')
+
 module.exports = require('./lib/init')
+
+/**
+ * Max supported TTL, 365 days in seconds
+ * @type {number}
+ */
+module.exports.MAX_TTL = MAX_TTL_SECONDS

lib/AdobeState.js

@@ -28,7 +28,8 @@ const {
   MAX_LIST_COUNT_HINT,
   REQUEST_ID_HEADER,
   MIN_LIST_COUNT_HINT,
-  REGEX_PATTERN_LIST_KEY_MATCH
+  REGEX_PATTERN_LIST_KEY_MATCH,
+  MAX_TTL_SECONDS
 } = require('./constants')
 
 /* *********************************** typedefs *********************************** */
@@ -48,8 +49,10 @@ const {
  *
  * @typedef AdobeStatePutOptions
  * @type {object}
- * @property {number} ttl time-to-live for key-value pair in seconds, defaults to 24 hours (86400s). Set to < 0 for max ttl of one year. A
- * value of 0 sets default.
+ * @property {number} ttl Time-To-Live for key-value pair in seconds. When not
+ *   defined or set to 0, defaults to 24 hours (86400s). Max TTL is one year
+ *   (31536000s), `require('@adobe/aio-lib-state').MAX_TTL`. A TTL of 0 defaults
+ *   to 24 hours.
  */
 
 /**
@@ -69,6 +72,7 @@ const {
  * @param {object} schema the AJV schema
  * @param {object} data the json data to test
  * @returns {object} the result
+ * @private
  */
 function validate (schema, data) {
   const ajv = new Ajv({ allErrors: true })
@@ -78,7 +82,7 @@ function validate (schema, data) {
   return { valid, errors: validate.errors }
 }
 
-// eslint-disable-next-line jsdoc/require-jsdoc
+/** @private */
 async function _wrap (promise, params) {
   let response
   try {
@@ -97,6 +101,7 @@ async function _wrap (promise, params) {
  * @param {Response} response a fetch Response
  * @param {object} params the params to the network call
  * @returns {void}
+ * @private
  */
 async function handleResponse (response, params) {
   if (response.ok) {
@@ -317,20 +322,31 @@ class AdobeState {
         },
         value: {
           type: 'string'
+        },
+        ttl: {
+          type: 'integer'
         }
       }
     }
 
-    const { valid, errors } = validate(schema, { key, value })
+    // validation
+    const { ttl } = options
+    const { valid, errors } = validate(schema, { key, value, ttl })
     if (!valid) {
       logAndThrow(new codes.ERROR_BAD_ARGUMENT({
         messageValues: utils.formatAjvErrors(errors),
-        sdkDetails: { key, value, options, errors }
+        sdkDetails: { key, valueLength: value.length, options, errors }
+      }))
+    }
+    if (ttl !== undefined && (ttl < 0 || ttl > MAX_TTL_SECONDS)) {
+      // error message is nicer like this than for
+      logAndThrow(new codes.ERROR_BAD_ARGUMENT({
+        messageValues: 'ttl must be <= 365 days (31536000s). Infinite TTLs (< 0) are not supported.',
+        sdkDetails: { key, valueLength: value.length, options }
       }))
     }
 
-    const { ttl } = options
-    const queryParams = ttl ? { ttl } : {}
+    const queryParams = ttl !== undefined ? { ttl } : {}
     const requestOptions = {
       method: 'PUT',
       headers: {

package.json

@@ -15,10 +15,12 @@
     "e2e": "jest -c jest.e2e.config.js",
     "jsdoc": "jsdoc2md -f index.js 'lib/**/*.js' > doc/api.md",
     "typings": "jsdoc -t node_modules/tsd-jsdoc/dist -r lib -d . && replace-in-file /declare/g export types.d.ts --isRegex",
-    "generate-docs": "npm run jsdoc && npm run typings"
+    "generate-docs": "npm run jsdoc && npm run typings",
+    "git-add-docs": "git add doc/ types.d.ts"
   },
   "pre-commit": [
-    "generate-docs"
+    "generate-docs",
+    "git-add-docs"
   ],
   "author": "Adobe Inc.",
   "license": "Apache-2.0",