@softistx/janus-redis 0.0.0-stage → 0.10.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,187 @@
1
+ # Troubleshooting `@softistx/janus-redis`
2
+
3
+ Installing `@softistx/janus*` fails with a 401 or 404? See
4
+ [the install entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#installing-softistx-packages).
5
+
6
+ Each entry is headed by the text you see: a compiler error, a message, or an
7
+ error `code`. Search this page for the words of your message.
8
+
9
+ This adapter **defines no error class**. Every error it throws is
10
+ `@softistx/janus`'s `StoreFailure`, with what Bun's Redis client threw as its
11
+ `cause`. The errors the core raises itself (`CREDENTIALS_INVALID`,
12
+ `TOKEN_EXPIRED`, …) are in
13
+ [`@softistx/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md).
14
+
15
+ ## Index
16
+
17
+ **Types**
18
+ - [`TS2345: Argument of type '…' is not assignable to parameter of type 'RedisConnection'.`](#ts2345-argument-of-type--is-not-assignable-to-parameter-of-type-redisconnection)
19
+ - [`TS2741: Property 'users' is missing in type 'RedisStores' but required in type 'JanusStores'.`](#ts2741-property-users-is-missing-in-type-redisstores-but-required-in-type-janusstores)
20
+
21
+ **Runtime**
22
+ - [`STORE_FAILED` after about 31 seconds, caused by `Max reconnection attempts reached`](#store_failed-after-about-31-seconds-caused-by-max-reconnection-attempts-reached)
23
+ - [`STORE_FAILED`: `sessions.<operation>: the store could not answer`](#store_failed-sessionsoperation-the-store-could-not-answer)
24
+ - [`STORE_FAILED`: `sessions.<operation>: a reply that is not … — a key under the prefix this adapter did not write`](#store_failed-sessionsoperation-a-reply-that-is-not---a-key-under-the-prefix-this-adapter-did-not-write)
25
+ - [`CROSSSLOT Keys in request don't hash to the same slot`, or `Script attempted to access a non local key in a cluster node`](#crossslot-keys-in-request-dont-hash-to-the-same-slot-or-script-attempted-to-access-a-non-local-key-in-a-cluster-node)
26
+ - [`UNSUPPORTED`: `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens …`](#unsupported-collectexpired-storesessions-does-not-implement-deleteexpiredsessions-nor-storetokens-deleteexpiredtokens-)
27
+ - [`TypeError: connectRedis: this URI is already connected with other options.`](#typeerror-connectredis-this-uri-is-already-connected-with-other-options)
28
+ - [Users are signed out after Redis restarts](#users-are-signed-out-after-redis-restarts)
29
+ - [Users are signed out while Redis is up, under memory pressure](#users-are-signed-out-while-redis-is-up-under-memory-pressure)
30
+
31
+ ---
32
+
33
+ ## Types
34
+
35
+ ### `TS2345: Argument of type '…' is not assignable to parameter of type 'RedisConnection'.`
36
+
37
+ `'…'` is `'string'` for a URL, or `RedisClient` for Bun's client.
38
+
39
+ **When:** you pass `createRedisStores` a URL, or a `RedisClient` you created
40
+ yourself.
41
+
42
+ **Why:** the adapter takes the connection `@softistx/redis`'s `connectRedis`
43
+ returns, and connects to nothing itself.
44
+
45
+ **Fix:**
46
+
47
+ ```ts
48
+ import { connectRedis } from '@softistx/redis';
49
+
50
+ const stores = createRedisStores(await connectRedis(process.env.REDIS_URL ?? 'redis://localhost:6379'));
51
+ ```
52
+
53
+ ### `TS2741: Property 'users' is missing in type 'RedisStores' but required in type 'JanusStores'.`
54
+
55
+ **When:** `janus({ store: createRedisStores(redis) })`.
56
+
57
+ **Why:** this adapter serves sessions and tokens only. Users need a store of
58
+ their own.
59
+
60
+ **Fix:** spread a users store first, then this one.
61
+
62
+ ```ts
63
+ store: { ...createDrizzleStores(db), ...createRedisStores(redis) },
64
+ ```
65
+
66
+ ---
67
+
68
+ ## Runtime
69
+
70
+ ### `STORE_FAILED` after about 31 seconds, caused by `Max reconnection attempts reached`
71
+
72
+ **When:** Redis is unreachable, and each request hangs for about half a minute
73
+ before it answers 503.
74
+
75
+ **Why:** Bun's client queues commands while it reconnects, and fails them only
76
+ once it gives up, after about 31 s measured.
77
+
78
+ **Fix:** turn the queue off for Janus's connection, so an outage fails at once
79
+ (1 ms measured):
80
+
81
+ ```ts
82
+ const redis = await connectRedis(process.env.REDIS_URL ?? 'redis://localhost:6379', {
83
+ enableOfflineQueue: false,
84
+ });
85
+ ```
86
+
87
+ ### `STORE_FAILED`: `sessions.<operation>: the store could not answer`
88
+
89
+ Also `tokens.<operation>: …`.
90
+
91
+ **When:** any call, for as long as Redis cannot answer: unreachable, out of
92
+ memory (`OOM`), a replica that refuses writes (`READONLY`), a user without the
93
+ right (`NOPERM`). With `enableOfflineQueue: false`, an outage's `cause` reads
94
+ `Connection is closed and offline queue is disabled`. From `insertSession`
95
+ only, a `cause` of `JANUS a session token hash is held by another session`
96
+ means two sessions were given one token hash: never the core's, which draws
97
+ 32 random bytes per session.
98
+
99
+ **Why:** the adapter never turns a failure into an absence. An outage is not
100
+ "no such session", which would sign every user out.
101
+
102
+ **Fix:** answer 503 and let the client retry. Log `cause` for Redis's reply.
103
+
104
+ ```ts
105
+ import { StoreFailure } from '@softistx/janus';
106
+
107
+ if (error instanceof StoreFailure) console.error(error.slot, error.operation, error.cause);
108
+ ```
109
+
110
+ A Redis user restricted by ACL needs `+@scripting` and the commands the scripts
111
+ run (`HSET`, `HGET`, `HGETALL`, `HINCRBY`, `EXISTS`, `GET`, `SET`, `DEL`, `SADD`, `SREM`,
112
+ `SMEMBERS`, `PTTL`, `PEXPIREAT`), on the keys `~janus:*`, or `~<your prefix>*`.
113
+
114
+ ### `STORE_FAILED`: `sessions.<operation>: a reply that is not … — a key under the prefix this adapter did not write`
115
+
116
+ Also `tokens.<operation>: …`, and `… not a date in \`expiresAt\``, `… not a
117
+ count in \`attempts\``, `… not a hash with \`userId\``, and the like.
118
+
119
+ **When:** Redis answered, but a key under the prefix holds something this
120
+ adapter did not write: a key set by hand, another application using the same
121
+ prefix, or a key written by another version.
122
+
123
+ **Why:** a record it cannot read is a failure, never an absence — answering
124
+ `null` would sign a user out, or refuse a valid reset link. There is no
125
+ `cause`: Redis did not fail.
126
+
127
+ **Fix:** give Janus a prefix no other code writes under, and delete the
128
+ foreign keys:
129
+
130
+ ```ts
131
+ createRedisStores(redis, { prefix: 'clinic:janus:' });
132
+ ```
133
+
134
+ ### `CROSSSLOT Keys in request don't hash to the same slot`, or `Script attempted to access a non local key in a cluster node`
135
+
136
+ The message is the `cause` of a `STORE_FAILED`.
137
+
138
+ **When:** Janus's Redis is a Redis Cluster.
139
+
140
+ **Why:** a script reads keys it finds on the way, a session's token key or a
141
+ user's set, which live in different hash slots. Cluster is not supported.
142
+
143
+ **Fix:** give Janus a single Redis, or a primary with replicas.
144
+
145
+ ### `UNSUPPORTED`: `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens …`
146
+
147
+ **When:** `auth.collectExpired()`.
148
+
149
+ **Why:** Redis expires every session and token key itself, at its
150
+ `expiresAt`. There is nothing to collect, so neither method is implemented.
151
+
152
+ **Fix:** remove the scheduled job.
153
+
154
+ ### `TypeError: connectRedis: this URI is already connected with other options.`
155
+
156
+ **When:** your application and Janus connect to the same Redis URI, one with
157
+ `enableOfflineQueue: false` and one without.
158
+
159
+ **Why:** `@softistx/redis` shares one client per URI, and one client has one set of
160
+ options.
161
+
162
+ **Fix:** pass the same options everywhere, or give Janus its own URI — another
163
+ database number is enough: `redis://localhost:6379/1`.
164
+
165
+ ### Users are signed out after Redis restarts
166
+
167
+ **When:** every session is gone after a restart or a failover, and pending
168
+ password reset links answer `TOKEN_UNKNOWN`.
169
+
170
+ **Why:** Redis kept them in memory only. Sessions are derived state: losing
171
+ them signs users out, which recovers.
172
+
173
+ **Fix:** if it matters, enable persistence (RDB snapshots, or AOF with
174
+ `appendfsync everysec`) on this Redis.
175
+
176
+ ### Users are signed out while Redis is up, under memory pressure
177
+
178
+ **When:** sessions disappear before their expiry, or "sign out everywhere"
179
+ misses some, and Redis's `evicted_keys` (in `INFO stats`) grows.
180
+
181
+ **Why:** Redis evicts keys when it reaches `maxmemory`. Every key this adapter
182
+ writes has an expiry, so `volatile-*` policies evict them as readily as
183
+ `allkeys-*`.
184
+
185
+ **Fix:** set `maxmemory-policy noeviction` on this Redis, or give Janus a Redis
186
+ of its own. With `noeviction`, a full Redis refuses writes with `OOM`, which
187
+ answers 503 rather than signing anyone out.
package/package.json CHANGED
@@ -1,6 +1,64 @@
1
1
  {
2
- "name": "@softistx/janus-redis",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@softistx/janus-redis",
3
+ "version": "0.10.4",
4
+ "description": "The Redis adapter for @softistx/janus on @softistx/redis: sessions and one-time tokens, expired by Redis itself",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "files": [
10
+ "dist",
11
+ "docs",
12
+ "README.md",
13
+ "package.json",
14
+ "LICENSE"
15
+ ],
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "keywords": [
25
+ "identity",
26
+ "authentication",
27
+ "sessions",
28
+ "redis",
29
+ "janus",
30
+ "typescript"
31
+ ],
32
+ "repository": {
33
+ "type": "git",
34
+ "url": "git+https://github.com/softistx/nxgt-janus.git",
35
+ "directory": "packages/janus-redis"
36
+ },
37
+ "publishConfig": {
38
+ "registry": "https://registry.npmjs.org/",
39
+ "access": "public"
40
+ },
41
+ "scripts": {
42
+ "build": "bun run ../../build.ts",
43
+ "test": "bun test src",
44
+ "typecheck": "bun check",
45
+ "typecheck:tsc": "tsc --noEmit"
46
+ },
47
+ "nxgt": {
48
+ "entrypoints": [
49
+ "src/index.ts"
50
+ ]
51
+ },
52
+ "devDependencies": {
53
+ "@softistx/redis": "0.24.0",
54
+ "@softistx/janus": "^0.74.0",
55
+ "@types/bun": "^1.4.4",
56
+ "redis-memory-server": "0.17.2",
57
+ "zod": "^4.6.7"
58
+ },
59
+ "peerDependencies": {
60
+ "@softistx/redis": ">=0.14.0 <1",
61
+ "@softistx/janus": "^0.74.0",
62
+ "typescript": "^6.0.3 || ^7.0.0"
63
+ }
64
+ }