euclid-ndk 0.2.0
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 +201 -0
- package/README.md +603 -0
- package/dist/auth/index.d.ts +18 -0
- package/dist/auth/index.d.ts.map +1 -0
- package/dist/auth/index.js +17 -0
- package/dist/auth/index.js.map +1 -0
- package/dist/auth/rfc9421.d.ts +112 -0
- package/dist/auth/rfc9421.d.ts.map +1 -0
- package/dist/auth/rfc9421.js +452 -0
- package/dist/auth/rfc9421.js.map +1 -0
- package/dist/auth/scheme.d.ts +46 -0
- package/dist/auth/scheme.d.ts.map +1 -0
- package/dist/auth/scheme.js +44 -0
- package/dist/auth/scheme.js.map +1 -0
- package/dist/auth/signable.d.ts +37 -0
- package/dist/auth/signable.d.ts.map +1 -0
- package/dist/auth/signable.js +70 -0
- package/dist/auth/signable.js.map +1 -0
- package/dist/auth/sigv4.d.ts +72 -0
- package/dist/auth/sigv4.d.ts.map +1 -0
- package/dist/auth/sigv4.js +227 -0
- package/dist/auth/sigv4.js.map +1 -0
- package/dist/credentials.d.ts +56 -0
- package/dist/credentials.d.ts.map +1 -0
- package/dist/credentials.js +135 -0
- package/dist/credentials.js.map +1 -0
- package/dist/dto/com.d.ts +101 -0
- package/dist/dto/com.d.ts.map +1 -0
- package/dist/dto/com.js +132 -0
- package/dist/dto/com.js.map +1 -0
- package/dist/dto/eag.d.ts +104 -0
- package/dist/dto/eag.d.ts.map +1 -0
- package/dist/dto/eag.js +70 -0
- package/dist/dto/eag.js.map +1 -0
- package/dist/dto/eam.d.ts +105 -0
- package/dist/dto/eam.d.ts.map +1 -0
- package/dist/dto/eam.js +98 -0
- package/dist/dto/eam.js.map +1 -0
- package/dist/dto/eap.d.ts +88 -0
- package/dist/dto/eap.d.ts.map +1 -0
- package/dist/dto/eap.js +54 -0
- package/dist/dto/eap.js.map +1 -0
- package/dist/dto/ekm.d.ts +109 -0
- package/dist/dto/ekm.d.ts.map +1 -0
- package/dist/dto/ekm.js +78 -0
- package/dist/dto/ekm.js.map +1 -0
- package/dist/dto/ekv.d.ts +73 -0
- package/dist/dto/ekv.d.ts.map +1 -0
- package/dist/dto/ekv.js +45 -0
- package/dist/dto/ekv.js.map +1 -0
- package/dist/dto/ens.d.ts +84 -0
- package/dist/dto/ens.d.ts.map +1 -0
- package/dist/dto/ens.js +72 -0
- package/dist/dto/ens.js.map +1 -0
- package/dist/dto/eqs.d.ts +160 -0
- package/dist/dto/eqs.d.ts.map +1 -0
- package/dist/dto/eqs.js +120 -0
- package/dist/dto/eqs.js.map +1 -0
- package/dist/dto/esm.d.ts +192 -0
- package/dist/dto/esm.d.ts.map +1 -0
- package/dist/dto/esm.js +147 -0
- package/dist/dto/esm.js.map +1 -0
- package/dist/dto/ess.d.ts +49 -0
- package/dist/dto/ess.d.ts.map +1 -0
- package/dist/dto/ess.js +30 -0
- package/dist/dto/ess.js.map +1 -0
- package/dist/dto/json.d.ts +24 -0
- package/dist/dto/json.d.ts.map +1 -0
- package/dist/dto/json.js +47 -0
- package/dist/dto/json.js.map +1 -0
- package/dist/errors.d.ts +40 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +73 -0
- package/dist/errors.js.map +1 -0
- package/dist/http/client.d.ts +96 -0
- package/dist/http/client.d.ts.map +1 -0
- package/dist/http/client.js +258 -0
- package/dist/http/client.js.map +1 -0
- package/dist/index.d.ts +93 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +110 -0
- package/dist/index.js.map +1 -0
- package/dist/modules/base.d.ts +121 -0
- package/dist/modules/base.d.ts.map +1 -0
- package/dist/modules/base.js +142 -0
- package/dist/modules/base.js.map +1 -0
- package/dist/modules/eag.d.ts +166 -0
- package/dist/modules/eag.d.ts.map +1 -0
- package/dist/modules/eag.js +189 -0
- package/dist/modules/eag.js.map +1 -0
- package/dist/modules/eam.d.ts +314 -0
- package/dist/modules/eam.d.ts.map +1 -0
- package/dist/modules/eam.js +641 -0
- package/dist/modules/eam.js.map +1 -0
- package/dist/modules/eap.d.ts +204 -0
- package/dist/modules/eap.d.ts.map +1 -0
- package/dist/modules/eap.js +218 -0
- package/dist/modules/eap.js.map +1 -0
- package/dist/modules/ekm.d.ts +182 -0
- package/dist/modules/ekm.d.ts.map +1 -0
- package/dist/modules/ekm.js +228 -0
- package/dist/modules/ekm.js.map +1 -0
- package/dist/modules/ekv.d.ts +189 -0
- package/dist/modules/ekv.d.ts.map +1 -0
- package/dist/modules/ekv.js +212 -0
- package/dist/modules/ekv.js.map +1 -0
- package/dist/modules/ens.d.ts +122 -0
- package/dist/modules/ens.d.ts.map +1 -0
- package/dist/modules/ens.js +167 -0
- package/dist/modules/ens.js.map +1 -0
- package/dist/modules/eqs.d.ts +283 -0
- package/dist/modules/eqs.d.ts.map +1 -0
- package/dist/modules/eqs.js +355 -0
- package/dist/modules/eqs.js.map +1 -0
- package/dist/modules/esm.d.ts +358 -0
- package/dist/modules/esm.d.ts.map +1 -0
- package/dist/modules/esm.js +660 -0
- package/dist/modules/esm.js.map +1 -0
- package/dist/modules/ess.d.ts +96 -0
- package/dist/modules/ess.d.ts.map +1 -0
- package/dist/modules/ess.js +110 -0
- package/dist/modules/ess.js.map +1 -0
- package/dist/url.d.ts +31 -0
- package/dist/url.d.ts.map +1 -0
- package/dist/url.js +47 -0
- package/dist/url.js.map +1 -0
- package/package.json +47 -0
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ENS - euclid's notification module: topics, published messages, and the subscriptions that deliver
|
|
3
|
+
* them onward.
|
|
4
|
+
*
|
|
5
|
+
* One object, {@link EuclidEns}, built from a session that has already logged in:
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* const ens = session.ens();
|
|
9
|
+
* const topic = await ens.createTopic("order-events");
|
|
10
|
+
*
|
|
11
|
+
* await ens.subscribe(topic.ern, await session.eqs().getQueueErn("orders"));
|
|
12
|
+
* await ens.publishMessage(topic.ern, JSON.stringify({ order: 17 }));
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* The difference from EQS is what happens to a message once it is there. A queue holds a message until
|
|
16
|
+
* a consumer takes it; a topic hands each message to every subscriber and keeps it as a record of having
|
|
17
|
+
* done so. So there is no receive here, and no receipt handle: a subscriber consumes from its own queue,
|
|
18
|
+
* which is where the message was delivered.
|
|
19
|
+
*/
|
|
20
|
+
import { type SubscribeResult, type Subscription, type VariantInput } from "../dto/com.js";
|
|
21
|
+
import { type Page } from "../dto/eam.js";
|
|
22
|
+
import { type CreateTopicResult, type Topic, type TopicMessage, type TopicMessageAttribute, type TopicMessageCount, type TopicMetadata } from "../dto/ens.js";
|
|
23
|
+
import { ModuleClient, type ListOptions, type PageOptions } from "./base.js";
|
|
24
|
+
import type { EuclidSession } from "./eam.js";
|
|
25
|
+
export declare const TARGET = "ens";
|
|
26
|
+
/** The largest message a topic accepts, in bytes. */
|
|
27
|
+
export declare const DEFAULT_MAX_MESSAGE_LENGTH: number;
|
|
28
|
+
/** What a published message carries besides its body. */
|
|
29
|
+
export interface PublishMessageOptions {
|
|
30
|
+
/** The publisher's own attributes, which travel onto the queues the message is delivered to. */
|
|
31
|
+
attributes?: Record<string, VariantInput>;
|
|
32
|
+
/** `LOW`, `MIDDLE` or `HIGH`; left empty, the topic's own default applies. */
|
|
33
|
+
priority?: string;
|
|
34
|
+
}
|
|
35
|
+
/** Which account's topics a blanket purge applies to. All three default to the session's own. */
|
|
36
|
+
export interface PurgeAllTopicsOptions {
|
|
37
|
+
region?: string;
|
|
38
|
+
accountId?: string;
|
|
39
|
+
namespace?: string;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* ENS's operations, on the credentials of the session that created it.
|
|
43
|
+
*
|
|
44
|
+
* Built by {@link EuclidSession.ens} rather than directly, so that it shares that session's identity,
|
|
45
|
+
* namespace and connection settings - and follows them as they change.
|
|
46
|
+
*/
|
|
47
|
+
export declare class EuclidEns extends ModuleClient {
|
|
48
|
+
constructor(session: EuclidSession);
|
|
49
|
+
/** Creates a topic, and answers with the ERN everything else names it by. */
|
|
50
|
+
createTopic(name: string, maxMessageLength?: number): Promise<CreateTopicResult>;
|
|
51
|
+
/** Deletes a topic, its messages and its subscriptions. */
|
|
52
|
+
deleteTopic(ern: string): Promise<void>;
|
|
53
|
+
/** One page of topics, and how many exist in total. */
|
|
54
|
+
listTopics(options?: ListOptions): Promise<Page<Topic>>;
|
|
55
|
+
/** The ERN of the topic of this name, in the session's account and namespace. */
|
|
56
|
+
getTopicErn(name: string): Promise<string>;
|
|
57
|
+
/** Where a topic lives and how much has been published to it. */
|
|
58
|
+
getTopicMetadata(ern: string): Promise<TopicMetadata>;
|
|
59
|
+
/**
|
|
60
|
+
* Deletes every message a topic has kept, leaving the topic and its subscriptions in place.
|
|
61
|
+
*
|
|
62
|
+
* It does not un-deliver anything: a message already handed to a subscriber is on that subscriber's
|
|
63
|
+
* queue and belongs to it now.
|
|
64
|
+
*/
|
|
65
|
+
purgeTopic(ern: string): Promise<void>;
|
|
66
|
+
/**
|
|
67
|
+
* Purges every topic of an account, which defaults to this session's own.
|
|
68
|
+
*
|
|
69
|
+
* As blunt as it sounds, and there is no undo: it exists for a test environment between runs.
|
|
70
|
+
*/
|
|
71
|
+
purgeAllTopics(options?: PurgeAllTopicsOptions): Promise<void>;
|
|
72
|
+
/** Tags a topic. */
|
|
73
|
+
addTopicTag(ern: string, key: string, value: string): Promise<void>;
|
|
74
|
+
/** Sets the value of a tag the topic already has. */
|
|
75
|
+
setTopicTag(ern: string, key: string, value: string): Promise<void>;
|
|
76
|
+
/** Removes a tag from a topic. */
|
|
77
|
+
deleteTopicTag(ern: string, key: string): Promise<void>;
|
|
78
|
+
/**
|
|
79
|
+
* Publishes a message to a topic, and answers with the ID the server gave it.
|
|
80
|
+
*
|
|
81
|
+
* Every subscription on the topic gets a copy, each on its own queue and each consumed independently:
|
|
82
|
+
* a subscriber that is slow or stopped delays nobody else, and a message already delivered is not
|
|
83
|
+
* withdrawn if the subscription is later removed.
|
|
84
|
+
*/
|
|
85
|
+
publishMessage(topicErn: string, body: string, options?: PublishMessageOptions): Promise<string>;
|
|
86
|
+
/** One page of the messages a topic has kept, and how many it holds in total. */
|
|
87
|
+
listMessages(topicErn: string, options?: PageOptions): Promise<Page<TopicMessage>>;
|
|
88
|
+
/** A topic's message counters: what is on it, what went out, and what had to go out again. */
|
|
89
|
+
getMessageCount(ern: string): Promise<TopicMessageCount>;
|
|
90
|
+
/**
|
|
91
|
+
* One attribute of one published message.
|
|
92
|
+
*
|
|
93
|
+
* The attribute's name travels as `key` throughout ENS and as `name` in most of EQS - the server's own
|
|
94
|
+
* asymmetry, reproduced rather than papered over.
|
|
95
|
+
*/
|
|
96
|
+
getMessageAttribute(messageId: string, key: string): Promise<TopicMessageAttribute>;
|
|
97
|
+
/** Sets one attribute of one published message, creating it if it was not there. */
|
|
98
|
+
setMessageAttribute(messageId: string, key: string, value: VariantInput): Promise<TopicMessageAttribute>;
|
|
99
|
+
/**
|
|
100
|
+
* Delivers a topic's messages onward to a queue from now on.
|
|
101
|
+
*
|
|
102
|
+
* Only {@link QUEUE} is a target type so far, so `targetErn` names an EQS queue. A message published
|
|
103
|
+
* before this call is not delivered retrospectively - a subscription says what happens next.
|
|
104
|
+
*
|
|
105
|
+
* Not idempotent: a second call registers a second subscription and the queue then receives every
|
|
106
|
+
* message twice, so a caller that may run twice checks {@link listSubscriptions} first.
|
|
107
|
+
*/
|
|
108
|
+
subscribe(topicErn: string, targetErn: string, targetType?: string): Promise<SubscribeResult>;
|
|
109
|
+
/**
|
|
110
|
+
* Removes a subscription, by the ERN {@link subscribe} answered with - not the topic's, and not the
|
|
111
|
+
* queue's.
|
|
112
|
+
*/
|
|
113
|
+
unsubscribe(ern: string): Promise<void>;
|
|
114
|
+
/** Every subscription currently registered on a topic. */
|
|
115
|
+
listSubscriptions(topicErn: string): Promise<Subscription[]>;
|
|
116
|
+
/**
|
|
117
|
+
* ENS's own metrics, as the server collects them. Answered unparsed - the shape belongs to the
|
|
118
|
+
* monitoring module rather than to ENS.
|
|
119
|
+
*/
|
|
120
|
+
metrics(): Promise<Record<string, unknown>>;
|
|
121
|
+
}
|
|
122
|
+
//# sourceMappingURL=ens.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ens.d.ts","sourceRoot":"","sources":["../../src/modules/ens.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ENS - euclid's notification module: topics, published messages, and the subscriptions that deliver
|
|
3
|
+
* them onward.
|
|
4
|
+
*
|
|
5
|
+
* One object, {@link EuclidEns}, built from a session that has already logged in:
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* const ens = session.ens();
|
|
9
|
+
* const topic = await ens.createTopic("order-events");
|
|
10
|
+
*
|
|
11
|
+
* await ens.subscribe(topic.ern, await session.eqs().getQueueErn("orders"));
|
|
12
|
+
* await ens.publishMessage(topic.ern, JSON.stringify({ order: 17 }));
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* The difference from EQS is what happens to a message once it is there. A queue holds a message until
|
|
16
|
+
* a consumer takes it; a topic hands each message to every subscriber and keeps it as a record of having
|
|
17
|
+
* done so. So there is no receive here, and no receipt handle: a subscriber consumes from its own queue,
|
|
18
|
+
* which is where the message was delivered.
|
|
19
|
+
*/
|
|
20
|
+
import { QUEUE, toSubscribeResult, toSubscription, variantMapToJson, variantOf, variantToJson, } from "../dto/com.js";
|
|
21
|
+
import { toPage } from "../dto/eam.js";
|
|
22
|
+
import { toCreateTopicResult, toTopic, toTopicMessage, toTopicMessageAttribute, toTopicMessageCount, toTopicMetadata, } from "../dto/ens.js";
|
|
23
|
+
import { listPayload, ModuleClient, pagePayload } from "./base.js";
|
|
24
|
+
export const TARGET = "ens";
|
|
25
|
+
/** The largest message a topic accepts, in bytes. */
|
|
26
|
+
export const DEFAULT_MAX_MESSAGE_LENGTH = 1024 * 1024;
|
|
27
|
+
/**
|
|
28
|
+
* ENS's operations, on the credentials of the session that created it.
|
|
29
|
+
*
|
|
30
|
+
* Built by {@link EuclidSession.ens} rather than directly, so that it shares that session's identity,
|
|
31
|
+
* namespace and connection settings - and follows them as they change.
|
|
32
|
+
*/
|
|
33
|
+
export class EuclidEns extends ModuleClient {
|
|
34
|
+
constructor(session) {
|
|
35
|
+
super(session, { target: TARGET });
|
|
36
|
+
}
|
|
37
|
+
// -- topics ----------------------------------------------------------------------------------
|
|
38
|
+
/** Creates a topic, and answers with the ERN everything else names it by. */
|
|
39
|
+
async createTopic(name, maxMessageLength = DEFAULT_MAX_MESSAGE_LENGTH) {
|
|
40
|
+
return toCreateTopicResult(await this.call("create-topic", { name, maxMessageLength }));
|
|
41
|
+
}
|
|
42
|
+
/** Deletes a topic, its messages and its subscriptions. */
|
|
43
|
+
async deleteTopic(ern) {
|
|
44
|
+
await this.call("delete-topic", { ern });
|
|
45
|
+
}
|
|
46
|
+
/** One page of topics, and how many exist in total. */
|
|
47
|
+
async listTopics(options = {}) {
|
|
48
|
+
return toPage(await this.call("list-topics", listPayload(options, "name")), "topics", toTopic);
|
|
49
|
+
}
|
|
50
|
+
/** The ERN of the topic of this name, in the session's account and namespace. */
|
|
51
|
+
async getTopicErn(name) {
|
|
52
|
+
return this.textOf("get-topic-ern", { name }, "ern");
|
|
53
|
+
}
|
|
54
|
+
/** Where a topic lives and how much has been published to it. */
|
|
55
|
+
async getTopicMetadata(ern) {
|
|
56
|
+
return toTopicMetadata(await this.call("get-topic-metadata", { ern }));
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Deletes every message a topic has kept, leaving the topic and its subscriptions in place.
|
|
60
|
+
*
|
|
61
|
+
* It does not un-deliver anything: a message already handed to a subscriber is on that subscriber's
|
|
62
|
+
* queue and belongs to it now.
|
|
63
|
+
*/
|
|
64
|
+
async purgeTopic(ern) {
|
|
65
|
+
await this.call("purge-topic", { ern });
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Purges every topic of an account, which defaults to this session's own.
|
|
69
|
+
*
|
|
70
|
+
* As blunt as it sounds, and there is no undo: it exists for a test environment between runs.
|
|
71
|
+
*/
|
|
72
|
+
async purgeAllTopics(options = {}) {
|
|
73
|
+
await this.call("purge-all-topics", {
|
|
74
|
+
region: options.region || this.session.region,
|
|
75
|
+
accountId: options.accountId || this.session.accountId,
|
|
76
|
+
nameSpace: options.namespace || this.session.namespace,
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
/** Tags a topic. */
|
|
80
|
+
async addTopicTag(ern, key, value) {
|
|
81
|
+
await this.call("add-topic-tag", { ern, key, value });
|
|
82
|
+
}
|
|
83
|
+
/** Sets the value of a tag the topic already has. */
|
|
84
|
+
async setTopicTag(ern, key, value) {
|
|
85
|
+
await this.call("set-topic-tag", { ern, key, value });
|
|
86
|
+
}
|
|
87
|
+
/** Removes a tag from a topic. */
|
|
88
|
+
async deleteTopicTag(ern, key) {
|
|
89
|
+
await this.call("delete-topic-tag", { ern, key });
|
|
90
|
+
}
|
|
91
|
+
// -- messages --------------------------------------------------------------------------------
|
|
92
|
+
/**
|
|
93
|
+
* Publishes a message to a topic, and answers with the ID the server gave it.
|
|
94
|
+
*
|
|
95
|
+
* Every subscription on the topic gets a copy, each on its own queue and each consumed independently:
|
|
96
|
+
* a subscriber that is slow or stopped delays nobody else, and a message already delivered is not
|
|
97
|
+
* withdrawn if the subscription is later removed.
|
|
98
|
+
*/
|
|
99
|
+
async publishMessage(topicErn, body, options = {}) {
|
|
100
|
+
const payload = {
|
|
101
|
+
ern: topicErn,
|
|
102
|
+
body,
|
|
103
|
+
attributes: variantMapToJson(options.attributes),
|
|
104
|
+
};
|
|
105
|
+
if (options.priority)
|
|
106
|
+
payload["priority"] = options.priority;
|
|
107
|
+
return this.textOf("publish-message", payload, "messageId");
|
|
108
|
+
}
|
|
109
|
+
/** One page of the messages a topic has kept, and how many it holds in total. */
|
|
110
|
+
async listMessages(topicErn, options = {}) {
|
|
111
|
+
const payload = { topicErn, ...pagePayload(options, "created") };
|
|
112
|
+
return toPage(await this.call("list-messages", payload), "messages", toTopicMessage);
|
|
113
|
+
}
|
|
114
|
+
/** A topic's message counters: what is on it, what went out, and what had to go out again. */
|
|
115
|
+
async getMessageCount(ern) {
|
|
116
|
+
return toTopicMessageCount(await this.call("get-message-count", { ern }));
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* One attribute of one published message.
|
|
120
|
+
*
|
|
121
|
+
* The attribute's name travels as `key` throughout ENS and as `name` in most of EQS - the server's own
|
|
122
|
+
* asymmetry, reproduced rather than papered over.
|
|
123
|
+
*/
|
|
124
|
+
async getMessageAttribute(messageId, key) {
|
|
125
|
+
return toTopicMessageAttribute(await this.call("get-message-attribute", { messageId, key }));
|
|
126
|
+
}
|
|
127
|
+
/** Sets one attribute of one published message, creating it if it was not there. */
|
|
128
|
+
async setMessageAttribute(messageId, key, value) {
|
|
129
|
+
const payload = { messageId, key, value: variantToJson(variantOf(value)) };
|
|
130
|
+
return toTopicMessageAttribute(await this.call("set-message-attribute", payload));
|
|
131
|
+
}
|
|
132
|
+
// -- subscriptions ---------------------------------------------------------------------------
|
|
133
|
+
/**
|
|
134
|
+
* Delivers a topic's messages onward to a queue from now on.
|
|
135
|
+
*
|
|
136
|
+
* Only {@link QUEUE} is a target type so far, so `targetErn` names an EQS queue. A message published
|
|
137
|
+
* before this call is not delivered retrospectively - a subscription says what happens next.
|
|
138
|
+
*
|
|
139
|
+
* Not idempotent: a second call registers a second subscription and the queue then receives every
|
|
140
|
+
* message twice, so a caller that may run twice checks {@link listSubscriptions} first.
|
|
141
|
+
*/
|
|
142
|
+
async subscribe(topicErn, targetErn, targetType = QUEUE) {
|
|
143
|
+
return toSubscribeResult(await this.call("subscribe", { sourceErn: topicErn, type: targetType, targetErn }));
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Removes a subscription, by the ERN {@link subscribe} answered with - not the topic's, and not the
|
|
147
|
+
* queue's.
|
|
148
|
+
*/
|
|
149
|
+
async unsubscribe(ern) {
|
|
150
|
+
await this.call("unsubscribe", { ern });
|
|
151
|
+
}
|
|
152
|
+
/** Every subscription currently registered on a topic. */
|
|
153
|
+
async listSubscriptions(topicErn) {
|
|
154
|
+
const response = await this.call("list-subscriptions", { topicErn });
|
|
155
|
+
const subscriptions = response["subscriptions"];
|
|
156
|
+
return Array.isArray(subscriptions) ? subscriptions.map(toSubscription) : [];
|
|
157
|
+
}
|
|
158
|
+
// -- monitoring ------------------------------------------------------------------------------
|
|
159
|
+
/**
|
|
160
|
+
* ENS's own metrics, as the server collects them. Answered unparsed - the shape belongs to the
|
|
161
|
+
* monitoring module rather than to ENS.
|
|
162
|
+
*/
|
|
163
|
+
async metrics() {
|
|
164
|
+
return this.call("get-metrics");
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
//# sourceMappingURL=ens.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ens.js","sourceRoot":"","sources":["../../src/modules/ens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,aAAa,GAId,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAa,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,mBAAmB,EACnB,OAAO,EACP,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAOhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAsC,MAAM,WAAW,CAAC;AAGvG,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,CAAC;AAE5B,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,GAAG,IAAI,CAAC;AAiBtD;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,YAAY;IACzC,YAAY,OAAsB;QAChC,KAAK,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,+FAA+F;IAE/F,6EAA6E;IAC7E,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,gBAAgB,GAAG,0BAA0B;QAC3E,OAAO,mBAAmB,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,WAAW,CAAC,GAAW;QAC3B,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,UAAU,CAAC,UAAuB,EAAE;QACxC,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjG,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,WAAW,CAAC,IAAY;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,gBAAgB,CAAC,GAAW;QAChC,OAAO,eAAe,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,GAAW;QAC1B,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,cAAc,CAAC,UAAiC,EAAE;QACtD,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YAClC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM;YAC7C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS;YACtD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS;SACvD,CAAC,CAAC;IACL,CAAC;IAED,oBAAoB;IACpB,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,GAAW,EAAE,KAAa;QACvD,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,GAAW,EAAE,KAAa;QACvD,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,kCAAkC;IAClC,KAAK,CAAC,cAAc,CAAC,GAAW,EAAE,GAAW;QAC3C,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,+FAA+F;IAE/F;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAAC,QAAgB,EAAE,IAAY,EAAE,UAAiC,EAAE;QACtF,MAAM,OAAO,GAA4B;YACvC,GAAG,EAAE,QAAQ;YACb,IAAI;YACJ,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC;SACjD,CAAC;QACF,IAAI,OAAO,CAAC,QAAQ;YAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;QAC7D,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,UAAuB,EAAE;QAC5D,MAAM,OAAO,GAAG,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;QACjE,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;IACvF,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,eAAe,CAAC,GAAW;QAC/B,OAAO,mBAAmB,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,mBAAmB,CAAC,SAAiB,EAAE,GAAW;QACtD,OAAO,uBAAuB,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,mBAAmB,CACvB,SAAiB,EACjB,GAAW,EACX,KAAmB;QAEnB,MAAM,OAAO,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3E,OAAO,uBAAuB,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,+FAA+F;IAE/F;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,SAAiB,EAAE,UAAU,GAAG,KAAK;QACrE,OAAO,iBAAiB,CACtB,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CACnF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,GAAW;QAC3B,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QACtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrE,MAAM,aAAa,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;QAChD,OAAO,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,CAAC;IAED,+FAA+F;IAE/F;;;OAGG;IACH,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAClC,CAAC;CACF"}
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* EQS - euclid's queue module: queues, messages, leases, dead letter queues.
|
|
3
|
+
*
|
|
4
|
+
* One object, {@link EuclidEqs}, built from a session that has already logged in:
|
|
5
|
+
*
|
|
6
|
+
* ```ts
|
|
7
|
+
* const eqs = (await Euclid.forServer(url).login("jens", "secret")).eqs();
|
|
8
|
+
* const queue = await eqs.createQueue("orders");
|
|
9
|
+
*
|
|
10
|
+
* await eqs.sendMessage(queue.ern, JSON.stringify({ order: 17 }));
|
|
11
|
+
* for (const message of (await eqs.receiveMessages(queue.ern, { waitTimeSeconds: 20 })).items) {
|
|
12
|
+
* await handle(message.body);
|
|
13
|
+
* await eqs.deleteMessage(message.receiptHandle);
|
|
14
|
+
* }
|
|
15
|
+
* ```
|
|
16
|
+
*
|
|
17
|
+
* Receiving is a lease rather than a read: a message a consumer takes is invisible to every other
|
|
18
|
+
* consumer until its visibility timeout expires, and deleting it with the receipt handle is what says
|
|
19
|
+
* the work was done. A consumer that dies instead simply stops holding the lease, and the message comes
|
|
20
|
+
* back - which is why the delete belongs after the work rather than before it.
|
|
21
|
+
*/
|
|
22
|
+
import { type VariantInput } from "../dto/com.js";
|
|
23
|
+
import { type Page } from "../dto/eam.js";
|
|
24
|
+
import { type CreateQueueResult, type Queue, type QueueMessage, type QueueMessageAttribute, type QueueMessageCount, type QueueMessageMetadata, type QueueMetadata, type QueueStatusResult, type RedriveDlqResult } from "../dto/eqs.js";
|
|
25
|
+
import type { EuclidHttpClient } from "../http/client.js";
|
|
26
|
+
import { ModuleClient, type ListOptions, type PageOptions } from "./base.js";
|
|
27
|
+
import type { EuclidSession } from "./eam.js";
|
|
28
|
+
export declare const TARGET = "eqs";
|
|
29
|
+
/** How long a received message stays invisible before it goes back on the queue, in seconds. */
|
|
30
|
+
export declare const DEFAULT_VISIBILITY = 30;
|
|
31
|
+
/** How many times a message may be received before it goes to the dead letter queue. */
|
|
32
|
+
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
33
|
+
/** The largest message a queue accepts, in bytes. */
|
|
34
|
+
export declare const DEFAULT_MAX_MESSAGE_LENGTH: number;
|
|
35
|
+
/**
|
|
36
|
+
* How long to pause, in milliseconds, before asking again when the server answered a long poll
|
|
37
|
+
* immediately because it had no slot free to wait in. Only reached when the server is short of threads,
|
|
38
|
+
* which is the moment to ask less often rather than more.
|
|
39
|
+
*/
|
|
40
|
+
export declare const SLOTS_BUSY_BACKOFF_MS = 500;
|
|
41
|
+
/**
|
|
42
|
+
* How close to its deadline a long poll may come back and still count as having been waited out rather
|
|
43
|
+
* than answered early. Absorbs the jitter between the server's clock and this one, so an honoured wait
|
|
44
|
+
* is not followed by a pointless extra request for the last few milliseconds.
|
|
45
|
+
*/
|
|
46
|
+
export declare const HONOURED_WAIT_TOLERANCE_MS = 250;
|
|
47
|
+
/**
|
|
48
|
+
* Added to a long poll's wait to give the response time to travel: the server answers at the end of the
|
|
49
|
+
* window it was asked for, so a timeout of exactly that window would race the network.
|
|
50
|
+
*/
|
|
51
|
+
export declare const LONG_POLL_RESPONSE_MARGIN_MS = 10000;
|
|
52
|
+
/** What a queue is created with. Every field has a server-side default. */
|
|
53
|
+
export interface CreateQueueOptions {
|
|
54
|
+
/** How long a received message stays invisible, in seconds, unless a receive says otherwise. */
|
|
55
|
+
visibility?: number;
|
|
56
|
+
/**
|
|
57
|
+
* How many times a message may be received before it is moved to `dlqName`. A queue without a dead
|
|
58
|
+
* letter queue keeps redelivering.
|
|
59
|
+
*/
|
|
60
|
+
maxRetries?: number;
|
|
61
|
+
/** The largest message this queue accepts, in bytes. */
|
|
62
|
+
maxMessageLength?: number;
|
|
63
|
+
/** The name of the queue that failed messages end up on. */
|
|
64
|
+
dlqName?: string;
|
|
65
|
+
/** How long a sent message waits before it can be received at all, in seconds. */
|
|
66
|
+
delay?: number;
|
|
67
|
+
/**
|
|
68
|
+
* The priority every message of this queue gets unless a send overrides it -
|
|
69
|
+
* {@link import("../dto/com.js").PRIORITY_LOW} and its siblings, or the server's default when left
|
|
70
|
+
* empty.
|
|
71
|
+
*/
|
|
72
|
+
priority?: string;
|
|
73
|
+
/** Marks the queue as euclid's own plumbing, which leaves it out of an ordinary listing. */
|
|
74
|
+
internal?: boolean;
|
|
75
|
+
}
|
|
76
|
+
/** How a queue listing is paged, and whether euclid's own queues are in it. */
|
|
77
|
+
export interface ListQueuesOptions extends ListOptions {
|
|
78
|
+
includeInternal?: boolean;
|
|
79
|
+
}
|
|
80
|
+
/** What a message carries besides its body. */
|
|
81
|
+
export interface SendMessageOptions {
|
|
82
|
+
/** The sender's own attributes, which come back on the received message. */
|
|
83
|
+
attributes?: Record<string, VariantInput>;
|
|
84
|
+
/**
|
|
85
|
+
* euclid's envelope, which travels with the message across every hop - what lets a service pass on
|
|
86
|
+
* what it received rather than what it happens to know.
|
|
87
|
+
*/
|
|
88
|
+
systemAttributes?: Record<string, VariantInput>;
|
|
89
|
+
/** `LOW`, `MIDDLE` or `HIGH`; left empty, the message takes the queue's own default. */
|
|
90
|
+
priority?: string;
|
|
91
|
+
}
|
|
92
|
+
/** How many messages a receive takes, and how long it is willing to wait for them. */
|
|
93
|
+
export interface ReceiveMessagesOptions {
|
|
94
|
+
maxMessages?: number;
|
|
95
|
+
/** How long the server may hold the request open, in seconds. Zero does not wait at all. */
|
|
96
|
+
waitTimeSeconds?: number;
|
|
97
|
+
}
|
|
98
|
+
/** Which account's queues a blanket purge applies to. Both default to the session's own. */
|
|
99
|
+
export interface PurgeAllQueuesOptions {
|
|
100
|
+
region?: string;
|
|
101
|
+
accountId?: string;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* EQS's operations, on the credentials of the session that created it.
|
|
105
|
+
*
|
|
106
|
+
* Built by {@link EuclidSession.eqs} rather than directly, so that it shares that session's identity,
|
|
107
|
+
* namespace and connection settings - and follows them as they change.
|
|
108
|
+
*/
|
|
109
|
+
export declare class EuclidEqs extends ModuleClient {
|
|
110
|
+
#private;
|
|
111
|
+
/**
|
|
112
|
+
* How long to pause before asking again when the server declined to wait out a long poll.
|
|
113
|
+
*
|
|
114
|
+
* A field rather than a constant because it is the one part of the polling a caller may reasonably
|
|
115
|
+
* want to change - and because nothing in a test suite wants to sit out a backoff that exists to be
|
|
116
|
+
* kind to a server short of threads.
|
|
117
|
+
*/
|
|
118
|
+
slotsBusyBackoffMs: number;
|
|
119
|
+
constructor(session: EuclidSession, options?: {
|
|
120
|
+
client?: EuclidHttpClient;
|
|
121
|
+
headers?: Record<string, string>;
|
|
122
|
+
});
|
|
123
|
+
/** Creates a queue, and answers with the ERN everything else names it by. */
|
|
124
|
+
createQueue(name: string, options?: CreateQueueOptions): Promise<CreateQueueResult>;
|
|
125
|
+
/** Deletes a queue and everything on it. */
|
|
126
|
+
deleteQueue(ern: string): Promise<void>;
|
|
127
|
+
/**
|
|
128
|
+
* One page of queues, and how many exist in total.
|
|
129
|
+
*
|
|
130
|
+
* euclid's own queues - the delivery queue behind a bucket listener, say - are left out unless
|
|
131
|
+
* `includeInternal` asks for them, so a listing shows what a person would recognise. A component
|
|
132
|
+
* looking for the queues it created has to ask.
|
|
133
|
+
*/
|
|
134
|
+
listQueues(options?: ListQueuesOptions): Promise<Page<Queue>>;
|
|
135
|
+
/** The ERN of the queue of this name, in the session's account and namespace. */
|
|
136
|
+
getQueueErn(name: string): Promise<string>;
|
|
137
|
+
/** Where a queue lives and how much is in it. */
|
|
138
|
+
getQueueMetadata(ern: string): Promise<QueueMetadata>;
|
|
139
|
+
/** Deletes every message on a queue, leaving the queue itself in place. */
|
|
140
|
+
purgeQueue(ern: string): Promise<void>;
|
|
141
|
+
/**
|
|
142
|
+
* Deletes every message on every queue of an account, which defaults to this session's own.
|
|
143
|
+
*
|
|
144
|
+
* Exactly as blunt as it sounds, and there is no undo: it exists for a test environment between runs
|
|
145
|
+
* rather than for anything that has consumers attached.
|
|
146
|
+
*/
|
|
147
|
+
purgeAllQueues(options?: PurgeAllQueuesOptions): Promise<void>;
|
|
148
|
+
/**
|
|
149
|
+
* Stops a queue, so it hands no more messages out.
|
|
150
|
+
*
|
|
151
|
+
* Messages already in flight are left alone: their consumer took them before the queue was stopped
|
|
152
|
+
* and is still entitled to finish, so deleting one still works. Only new receives are refused, with
|
|
153
|
+
* HTTP 409.
|
|
154
|
+
*/
|
|
155
|
+
stopQueue(ern: string): Promise<QueueStatusResult>;
|
|
156
|
+
/** Starts a queue that was stopped, so it hands messages out again. */
|
|
157
|
+
startQueue(ern: string): Promise<QueueStatusResult>;
|
|
158
|
+
/**
|
|
159
|
+
* Changes a queue's default visibility timeout, and answers with the one it now has.
|
|
160
|
+
*
|
|
161
|
+
* Only the default changes. Messages already in flight keep the window they were given when they were
|
|
162
|
+
* received, so this can neither expire a lease a consumer is still working on nor hold back a message
|
|
163
|
+
* its consumer has already given up on.
|
|
164
|
+
*/
|
|
165
|
+
setQueueVisibility(ern: string, visibility: number): Promise<number>;
|
|
166
|
+
/**
|
|
167
|
+
* Moves messages out of a dead letter queue and back onto the queues they came from.
|
|
168
|
+
*
|
|
169
|
+
* `ern` has to name a queue that some other queue points at as its dead letter queue; an ordinary
|
|
170
|
+
* queue is refused rather than redriven into itself. A named `targetErn` has to be one of the queues
|
|
171
|
+
* that feed it, since anything else would be a move rather than a redrive.
|
|
172
|
+
*
|
|
173
|
+
* Left unnamed, each message goes back where it came from - and a message whose origin was never
|
|
174
|
+
* recorded is left alone rather than guessed at. The result says how many, so a caller can name a
|
|
175
|
+
* target and deal with them deliberately.
|
|
176
|
+
*/
|
|
177
|
+
redriveDlq(ern: string, targetErn?: string): Promise<RedriveDlqResult>;
|
|
178
|
+
/** Tags a queue. */
|
|
179
|
+
addQueueTag(ern: string, key: string, value: string): Promise<void>;
|
|
180
|
+
/** Sets the value of a tag the queue already has. */
|
|
181
|
+
setQueueTag(ern: string, key: string, value: string): Promise<void>;
|
|
182
|
+
/** Removes a tag from a queue. */
|
|
183
|
+
deleteQueueTag(ern: string, key: string): Promise<void>;
|
|
184
|
+
/**
|
|
185
|
+
* Puts a message on a queue, and answers with the ID the server gave it.
|
|
186
|
+
*
|
|
187
|
+
* The envelope and the priority are left out of the request entirely when there is nothing to say
|
|
188
|
+
* about them, so the queue's own defaults are what apply rather than an empty string the server would
|
|
189
|
+
* have to interpret.
|
|
190
|
+
*/
|
|
191
|
+
sendMessage(queueErn: string, body: string, options?: SendMessageOptions): Promise<string>;
|
|
192
|
+
/**
|
|
193
|
+
* Takes up to `maxMessages` messages off a queue, waiting up to `waitTimeSeconds` for them.
|
|
194
|
+
*
|
|
195
|
+
* The waiting is the server's, not this client's: it holds the request open until a message lands or
|
|
196
|
+
* the time runs out, so an idle queue costs one request for the whole window rather than one per poll
|
|
197
|
+
* tick, and a message comes back the instant it is sent.
|
|
198
|
+
*
|
|
199
|
+
* The one case that loops is the server declining to wait. It keeps a bounded number of long-poll
|
|
200
|
+
* slots - one fewer than it has threads - so that consumers sitting in a wait cannot starve the
|
|
201
|
+
* producers trying to send to them; with none free it answers at once with whatever is on the queue.
|
|
202
|
+
* That comes back empty with time still on the clock, and the answer is to wait a moment and ask
|
|
203
|
+
* again rather than immediately, since asking again at once is what a server short of threads does not
|
|
204
|
+
* need.
|
|
205
|
+
*
|
|
206
|
+
* With no wait asked for, the queue's depth is checked first and an empty queue costs no receive at
|
|
207
|
+
* all - a receive is a write, and one that takes nothing is work the server did for nothing.
|
|
208
|
+
*/
|
|
209
|
+
receiveMessages(queueErn: string, options?: ReceiveMessagesOptions): Promise<Page<QueueMessage>>;
|
|
210
|
+
/**
|
|
211
|
+
* Takes everything off a queue, a batch at a time, until it comes back empty.
|
|
212
|
+
*
|
|
213
|
+
* For draining a queue rather than for consuming one: every message comes back on a lease, so a caller
|
|
214
|
+
* that does not delete them will see them all again once the visibility timeout expires.
|
|
215
|
+
*/
|
|
216
|
+
receiveAllMessages(queueErn: string, batchSize?: number): Promise<QueueMessage[]>;
|
|
217
|
+
/**
|
|
218
|
+
* One page of a queue's messages, without receiving them.
|
|
219
|
+
*
|
|
220
|
+
* A read rather than a lease: nothing here becomes invisible, nothing counts as a delivery, and
|
|
221
|
+
* nothing can be deleted by receipt handle afterwards. It is how a queue is inspected, not how it is
|
|
222
|
+
* consumed.
|
|
223
|
+
*/
|
|
224
|
+
listMessages(queueErn: string, options?: PageOptions): Promise<Page<QueueMessage>>;
|
|
225
|
+
/**
|
|
226
|
+
* Deletes a received message, by the handle the receive handed out.
|
|
227
|
+
*
|
|
228
|
+
* The handle is a lease: this works while the message's visibility timeout is still running and fails
|
|
229
|
+
* once it has expired and the message has gone back on the queue.
|
|
230
|
+
*/
|
|
231
|
+
deleteMessage(receiptHandle: string): Promise<void>;
|
|
232
|
+
/**
|
|
233
|
+
* Deletes a message by its ID, including one nobody has received.
|
|
234
|
+
*
|
|
235
|
+
* Bypasses the lease {@link deleteMessage} goes through, which is what makes it able to remove a
|
|
236
|
+
* message that is still waiting or still delayed. A euclid extension with no SQS equivalent.
|
|
237
|
+
*/
|
|
238
|
+
deleteMessageById(messageId: string): Promise<void>;
|
|
239
|
+
/** How many messages a queue holds, by the state they are in. */
|
|
240
|
+
getMessageCount(ern: string): Promise<QueueMessageCount>;
|
|
241
|
+
/** Everything about one message except its body. */
|
|
242
|
+
getMessageMetadata(messageId: string): Promise<QueueMessageMetadata>;
|
|
243
|
+
/**
|
|
244
|
+
* Changes how long one message stays invisible - extending a lease a consumer needs longer.
|
|
245
|
+
*
|
|
246
|
+
* Sent as `set-message-visibility`, the name that says what it changes and pairs with
|
|
247
|
+
* {@link setQueueVisibility}. euclid answers to `set-visibility` as well, which is what euclid-jdk
|
|
248
|
+
* sends and what a server older than the newer name knows it by; such a server refuses this with
|
|
249
|
+
* HTTP 404, and {@link ModuleClient.call} is the way round that.
|
|
250
|
+
*/
|
|
251
|
+
setMessageVisibility(messageId: string, visibility: number): Promise<void>;
|
|
252
|
+
/** One attribute of one message. */
|
|
253
|
+
getMessageAttribute(messageId: string, name: string): Promise<QueueMessageAttribute>;
|
|
254
|
+
/**
|
|
255
|
+
* Sets one attribute of one message, creating it if it was not there.
|
|
256
|
+
*
|
|
257
|
+
* The attribute's name travels as `key` on this action and as `name` on the one that reads it back -
|
|
258
|
+
* the server's own asymmetry, reproduced rather than papered over, so that a request built from this
|
|
259
|
+
* SDK matches what euclid-cli and euclid-jdk send.
|
|
260
|
+
*/
|
|
261
|
+
setMessageAttribute(messageId: string, name: string, value: VariantInput): Promise<QueueMessageAttribute>;
|
|
262
|
+
/**
|
|
263
|
+
* EQS's own metrics, as the server collects them. Answered unparsed - the shape belongs to the
|
|
264
|
+
* monitoring module rather than to EQS.
|
|
265
|
+
*/
|
|
266
|
+
metrics(): Promise<Record<string, unknown>>;
|
|
267
|
+
/**
|
|
268
|
+
* A view of this client whose requests are marked as euclid's own traffic.
|
|
269
|
+
*
|
|
270
|
+
* Some calls observe the system rather than use it: reading a queue's depth to report it, polling for
|
|
271
|
+
* a heartbeat. They are indistinguishable from real work by their action alone - the same
|
|
272
|
+
* `get-message-count` is a user's question one moment and a metric collector's poll the next - so the
|
|
273
|
+
* caller says which it is, and the server logs and scales accordingly. Instrumentation that polls
|
|
274
|
+
* every few seconds would otherwise keep a pool permanently awake and make an idle module look busy:
|
|
275
|
+
* the monitoring preventing the thing it exists to measure.
|
|
276
|
+
*
|
|
277
|
+
* A separate client rather than a flag on this one, so that no call has to remember to set it back -
|
|
278
|
+
* but the same connection, since two clients that differ by a header have no reason to differ by a
|
|
279
|
+
* socket. Closing either closes both, which the owning session does anyway.
|
|
280
|
+
*/
|
|
281
|
+
asInternal(): EuclidEqs;
|
|
282
|
+
}
|
|
283
|
+
//# sourceMappingURL=eqs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"eqs.d.ts","sourceRoot":"","sources":["../../src/modules/eqs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA8C,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9F,OAAO,EAAU,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAUL,KAAK,iBAAiB,EACtB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAe,YAAY,EAAe,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACvG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,eAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,QAAc,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAChD,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,4FAA4F;AAC5F,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,YAAY;;IACzC;;;;;;OAMG;IACH,kBAAkB,SAAyB;gBAE/B,OAAO,EAAE,aAAa,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,gBAAgB,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAO;IAMjH,6EAA6E;IACvE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAe7F,4CAA4C;IACtC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAKvE,iFAAiF;IAC3E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhD,iDAAiD;IAC3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAI3D,2EAA2E;IACrE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;;OAKG;IACG,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxE;;;;;;OAMG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIxD,uEAAuE;IACjE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzD;;;;;;OAMG;IACG,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1E;;;;;;;;;;OAUG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIxE,oBAAoB;IACd,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE,qDAAqD;IAC/C,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE,kCAAkC;IAC5B,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7D;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAapG;;;;;;;;;;;;;;;;OAgBG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAuB1G;;;;;OAKG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IASnF;;;;;;OAMG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAK5F;;;;;OAKG;IACG,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;;;;OAKG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,iEAAiE;IAC3D,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI9D,oDAAoD;IAC9C,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI1E;;;;;;;OAOG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,oCAAoC;IAC9B,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI1F;;;;;;OAMG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,qBAAqB,CAAC;IAOjC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIjD;;;;;;;;;;;;;OAaG;IACH,UAAU,IAAI,SAAS;CAkBxB"}
|