@softistx/janus-redis 0.0.0-stage → 0.10.3
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.
- package/LICENSE +21 -0
- package/README.md +167 -2
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +416 -0
- package/dist/index.js.map +16 -0
- package/dist/replies.d.ts +24 -0
- package/dist/replies.d.ts.map +1 -0
- package/dist/runner.d.ts +8 -0
- package/dist/runner.d.ts.map +1 -0
- package/dist/scripts/index.d.ts +17 -0
- package/dist/scripts/index.d.ts.map +1 -0
- package/dist/scripts/sessions.d.ts +48 -0
- package/dist/scripts/sessions.d.ts.map +1 -0
- package/dist/scripts/shared.d.ts +18 -0
- package/dist/scripts/shared.d.ts.map +1 -0
- package/dist/scripts/tokens.d.ts +34 -0
- package/dist/scripts/tokens.d.ts.map +1 -0
- package/dist/session-store.d.ts +4 -0
- package/dist/session-store.d.ts.map +1 -0
- package/dist/stores.d.ts +38 -0
- package/dist/stores.d.ts.map +1 -0
- package/docs/README.md +10 -0
- package/docs/guide/wiring.md +126 -0
- package/docs/roadmap.md +53 -0
- package/docs/troubleshooting.md +187 -0
- package/package.json +63 -5
|
@@ -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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@softistx/janus-redis",
|
|
3
|
+
"version": "0.10.3",
|
|
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.73.1",
|
|
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.73.1",
|
|
62
|
+
"typescript": "^6.0.3 || ^7.0.0"
|
|
63
|
+
}
|
|
64
|
+
}
|