@maschinenlesbar.org/ckan-cli 0.0.6 → 0.1.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/dist/src/cli/commands/catalogue.d.ts +1 -2
- package/dist/src/cli/commands/catalogue.js +11 -3
- package/dist/src/cli/commands/portal.d.ts +0 -1
- package/dist/src/cli/commands/portal.js +13 -12
- package/dist/src/cli/index.d.ts +0 -1
- package/dist/src/cli/index.js +0 -1
- package/dist/src/cli/io.d.ts +0 -1
- package/dist/src/cli/io.js +0 -1
- package/dist/src/cli/program.d.ts +0 -1
- package/dist/src/cli/program.js +2 -3
- package/dist/src/cli/run.d.ts +0 -1
- package/dist/src/cli/run.js +9 -2
- package/dist/src/cli/shared.d.ts +10 -15
- package/dist/src/cli/shared.js +29 -54
- package/dist/src/client/client.d.ts +7 -6
- package/dist/src/client/client.js +38 -22
- package/dist/src/client/engine.d.ts +28 -6
- package/dist/src/client/engine.js +40 -30
- package/dist/src/client/errors.d.ts +7 -1
- package/dist/src/client/errors.js +7 -1
- package/dist/src/client/http.d.ts +0 -1
- package/dist/src/client/http.js +41 -33
- package/dist/src/client/index.d.ts +6 -5
- package/dist/src/client/index.js +4 -4
- package/dist/src/client/portals-list.d.ts +0 -1
- package/dist/src/client/portals-list.js +0 -1
- package/dist/src/client/portals.d.ts +35 -2
- package/dist/src/client/portals.js +48 -3
- package/dist/src/client/query.d.ts +0 -1
- package/dist/src/client/query.js +0 -1
- package/dist/src/client/types.d.ts +0 -1
- package/dist/src/client/types.js +0 -1
- package/dist/src/client/validate.d.ts +55 -0
- package/dist/src/client/validate.js +119 -0
- package/dist/src/index.d.ts +0 -1
- package/dist/src/index.js +0 -1
- package/package.json +2 -1
- package/dist/src/cli/commands/catalogue.d.ts.map +0 -1
- package/dist/src/cli/commands/catalogue.js.map +0 -1
- package/dist/src/cli/commands/portal.d.ts.map +0 -1
- package/dist/src/cli/commands/portal.js.map +0 -1
- package/dist/src/cli/index.d.ts.map +0 -1
- package/dist/src/cli/index.js.map +0 -1
- package/dist/src/cli/io.d.ts.map +0 -1
- package/dist/src/cli/io.js.map +0 -1
- package/dist/src/cli/program.d.ts.map +0 -1
- package/dist/src/cli/program.js.map +0 -1
- package/dist/src/cli/run.d.ts.map +0 -1
- package/dist/src/cli/run.js.map +0 -1
- package/dist/src/cli/shared.d.ts.map +0 -1
- package/dist/src/cli/shared.js.map +0 -1
- package/dist/src/client/client.d.ts.map +0 -1
- package/dist/src/client/client.js.map +0 -1
- package/dist/src/client/engine.d.ts.map +0 -1
- package/dist/src/client/engine.js.map +0 -1
- package/dist/src/client/errors.d.ts.map +0 -1
- package/dist/src/client/errors.js.map +0 -1
- package/dist/src/client/http.d.ts.map +0 -1
- package/dist/src/client/http.js.map +0 -1
- package/dist/src/client/index.d.ts.map +0 -1
- package/dist/src/client/index.js.map +0 -1
- package/dist/src/client/portals-list.d.ts.map +0 -1
- package/dist/src/client/portals-list.js.map +0 -1
- package/dist/src/client/portals.d.ts.map +0 -1
- package/dist/src/client/portals.js.map +0 -1
- package/dist/src/client/query.d.ts.map +0 -1
- package/dist/src/client/query.js.map +0 -1
- package/dist/src/client/types.d.ts.map +0 -1
- package/dist/src/client/types.js.map +0 -1
- package/dist/src/index.d.ts.map +0 -1
- package/dist/src/index.js.map +0 -1
|
@@ -1,14 +1,23 @@
|
|
|
1
1
|
// Commands over the catalogue: datasets, their resources, publishers, themes
|
|
2
2
|
// and tags.
|
|
3
|
+
import { InvalidArgumentError } from "commander";
|
|
4
|
+
import { facetLimitProblem } from "../../client/validate.js";
|
|
3
5
|
import { action, collectNonEmpty, parseBoundedInt, parseIntArg, parseNonEmpty, parseOptionValue, renderJson, } from "../shared.js";
|
|
4
6
|
/**
|
|
5
7
|
* commander value-parser for a list --limit: 1 or more. CKAN reads `limit=0` as
|
|
6
8
|
* "no limit" and would send the whole list; leave --limit out for that.
|
|
7
9
|
*/
|
|
8
10
|
const parseLimit = parseBoundedInt(1, Number.MAX_SAFE_INTEGER);
|
|
9
|
-
/**
|
|
11
|
+
/**
|
|
12
|
+
* commander value-parser for --facet-limit: a count, or -1 for every value (the
|
|
13
|
+
* library's facetLimitProblem rule).
|
|
14
|
+
*/
|
|
10
15
|
function parseFacetLimit(value) {
|
|
11
|
-
|
|
16
|
+
const n = /^-\d+$/.test(value) ? Number(value) : parseIntArg(value);
|
|
17
|
+
const reason = facetLimitProblem(n);
|
|
18
|
+
if (reason !== undefined)
|
|
19
|
+
throw new InvalidArgumentError(reason);
|
|
20
|
+
return n;
|
|
12
21
|
}
|
|
13
22
|
export function registerCatalogueCommands(program, deps) {
|
|
14
23
|
program
|
|
@@ -105,4 +114,3 @@ export function registerCatalogueCommands(program, deps) {
|
|
|
105
114
|
renderJson(deps, global, await client.tagList({ query: opts["query"] }));
|
|
106
115
|
}));
|
|
107
116
|
}
|
|
108
|
-
//# sourceMappingURL=catalogue.js.map
|
|
@@ -1,28 +1,29 @@
|
|
|
1
1
|
// Commands about the portal itself rather than its datasets.
|
|
2
2
|
import { InvalidArgumentError } from "commander";
|
|
3
3
|
import { action, renderJson, toEngineOptions } from "../shared.js";
|
|
4
|
-
import {
|
|
4
|
+
import { checkPortals } from "../../client/portals.js";
|
|
5
5
|
import { PORTALS } from "../../client/portals-list.js";
|
|
6
|
-
|
|
7
|
-
const CHECK_CONCURRENCY = 6;
|
|
6
|
+
import { isBlank } from "../../client/validate.js";
|
|
8
7
|
/** commander accumulator for repeatable `key=value` pairs into a record. */
|
|
9
8
|
function collectKeyValue(value, previous = {}) {
|
|
10
9
|
const eq = value.indexOf("=");
|
|
11
10
|
// Throw commander's InvalidArgumentError (not a CkanError) so the failure is
|
|
12
11
|
// formatted as a usage error with `error:` prefix and help, consistent with
|
|
13
12
|
// other parse-time flag validation (e.g. `--rows abc`).
|
|
14
|
-
|
|
13
|
+
const key = value.slice(0, Math.max(eq, 0));
|
|
14
|
+
// A blank key (`=x`, ` =x`) names no parameter: the library refuses it too.
|
|
15
|
+
if (eq < 0 || isBlank(key)) {
|
|
15
16
|
throw new InvalidArgumentError(`Invalid --param "${value}". Expected key=value.`);
|
|
16
17
|
}
|
|
17
|
-
const key = value.slice(0, eq);
|
|
18
18
|
// Reject a duplicated key rather than silently overwriting the earlier value.
|
|
19
19
|
if (Object.prototype.hasOwnProperty.call(previous, key)) {
|
|
20
20
|
throw new InvalidArgumentError(`Duplicate --param key "${key}".`);
|
|
21
21
|
}
|
|
22
|
-
// A blank value
|
|
23
|
-
// `--param q=` would
|
|
22
|
+
// A blank value is refused by the library as well (CKAN reads an empty
|
|
23
|
+
// parameter as unset, so `--param q=` would run the action unfiltered); here it
|
|
24
|
+
// is a usage error that names the flag.
|
|
24
25
|
const paramValue = value.slice(eq + 1);
|
|
25
|
-
if (paramValue
|
|
26
|
+
if (isBlank(paramValue)) {
|
|
26
27
|
throw new InvalidArgumentError(`Invalid --param "${value}". The value must not be blank.`);
|
|
27
28
|
}
|
|
28
29
|
// A computed key in a literal is an own data property, even for `__proto__`.
|
|
@@ -59,10 +60,10 @@ export function registerPortalCommands(program, deps) {
|
|
|
59
60
|
renderJson(deps, global, PORTALS);
|
|
60
61
|
return;
|
|
61
62
|
}
|
|
62
|
-
const
|
|
63
|
-
|
|
64
|
-
|
|
63
|
+
const checked = await checkPortals(PORTALS, {
|
|
64
|
+
engineOptions: toEngineOptions(global),
|
|
65
|
+
createClient: deps.createClient,
|
|
66
|
+
});
|
|
65
67
|
renderJson(deps, global, checked);
|
|
66
68
|
});
|
|
67
69
|
}
|
|
68
|
-
//# sourceMappingURL=portal.js.map
|
package/dist/src/cli/index.d.ts
CHANGED
package/dist/src/cli/index.js
CHANGED
package/dist/src/cli/io.d.ts
CHANGED
package/dist/src/cli/io.js
CHANGED
package/dist/src/cli/program.js
CHANGED
|
@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
|
|
|
6
6
|
import { Command, InvalidArgumentError, Option } from "commander";
|
|
7
7
|
import { defaultIO } from "./io.js";
|
|
8
8
|
import { CkanClient } from "../client/client.js";
|
|
9
|
-
import { DEFAULT_BASE_URL, MAX_RETRIES } from "../client/engine.js";
|
|
9
|
+
import { DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS } from "../client/engine.js";
|
|
10
10
|
import { MAX_TIMEOUT_MS } from "../client/http.js";
|
|
11
11
|
import { redactUrl } from "../client/errors.js";
|
|
12
12
|
import { parseBaseUrl, parseBoundedInt, parseHeaderValue, parseIntArg, parsePortal } from "./shared.js";
|
|
@@ -52,7 +52,7 @@ export function buildProgram(deps = defaultDeps) {
|
|
|
52
52
|
.conflicts("baseUrl"))
|
|
53
53
|
.option("--timeout <ms>", "per-request timeout in milliseconds", parseBoundedInt(0, MAX_TIMEOUT_MS))
|
|
54
54
|
.option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
|
|
55
|
-
.option("--max-retries <n>",
|
|
55
|
+
.option("--max-retries <n>", `retries for transient 429/503 responses (0..${MAX_RETRIES}; each waits the server's Retry-After, up to ${MAX_RETRY_AFTER_MS / 1000} s)`, parseBoundedInt(0, MAX_RETRIES))
|
|
56
56
|
.option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
|
|
57
57
|
.option("--compact", "print JSON on a single line instead of pretty-printed")
|
|
58
58
|
.showHelpAfterError();
|
|
@@ -93,4 +93,3 @@ export function buildProgram(deps = defaultDeps) {
|
|
|
93
93
|
program.allowExcessArguments(true);
|
|
94
94
|
return program;
|
|
95
95
|
}
|
|
96
|
-
//# sourceMappingURL=program.js.map
|
package/dist/src/cli/run.d.ts
CHANGED
package/dist/src/cli/run.js
CHANGED
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
// captured output and exit code without spawning a subprocess.
|
|
4
4
|
import { CommanderError } from "commander";
|
|
5
5
|
import { buildProgram, defaultDeps } from "./program.js";
|
|
6
|
-
import { CkanApiError, CkanError } from "../client/errors.js";
|
|
6
|
+
import { CkanApiError, CkanError, CkanValidationError } from "../client/errors.js";
|
|
7
|
+
/** The exit code of a usage error: commander's own for a rejected option value. */
|
|
8
|
+
const USAGE_EXIT = 1;
|
|
7
9
|
/**
|
|
8
10
|
* Apply exitOverride + output redirection to every command in the tree.
|
|
9
11
|
* commander does not propagate these to subcommands, so a parse error on a
|
|
@@ -30,6 +32,12 @@ export async function run(argv, deps = defaultDeps) {
|
|
|
30
32
|
// Help/version requests exit 0; genuine parse errors carry their own code.
|
|
31
33
|
return err.exitCode;
|
|
32
34
|
}
|
|
35
|
+
if (err instanceof CkanValidationError) {
|
|
36
|
+
// An input the library refused before any request (a rule the commander
|
|
37
|
+
// parsers do not see, e.g. one across parameters): a usage error.
|
|
38
|
+
deps.io.err(`Error: ${err.message}`);
|
|
39
|
+
return USAGE_EXIT;
|
|
40
|
+
}
|
|
33
41
|
if (err instanceof CkanApiError) {
|
|
34
42
|
deps.io.err(`Error: ${err.message}`);
|
|
35
43
|
// Map a few notable statuses to distinct exit codes for scripting.
|
|
@@ -45,4 +53,3 @@ export async function run(argv, deps = defaultDeps) {
|
|
|
45
53
|
return 1;
|
|
46
54
|
}
|
|
47
55
|
}
|
|
48
|
-
//# sourceMappingURL=run.js.map
|
package/dist/src/cli/shared.d.ts
CHANGED
|
@@ -3,17 +3,14 @@ import { type EngineOptions } from "../client/engine.js";
|
|
|
3
3
|
/** commander value-parser: a non-negative integer. */
|
|
4
4
|
export declare function parseIntArg(value: string): number;
|
|
5
5
|
/**
|
|
6
|
-
* commander value-parser: a value that is not blank
|
|
7
|
-
*
|
|
6
|
+
* commander value-parser: a value that is not blank (the library's blankProblem
|
|
7
|
+
* rule, reported as a usage error before the client is built).
|
|
8
8
|
*/
|
|
9
9
|
export declare function parseNonEmpty(value: string): string;
|
|
10
10
|
/**
|
|
11
|
-
* commander value-parser for a value that ends up in an HTTP header (`--user-agent`)
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* U+00FF, which surfaced as "Unexpected error". Reject those here as a usage error,
|
|
15
|
-
* along with a blank value. Tab is allowed, as in HTTP. Checked by char code so the
|
|
16
|
-
* source stays free of control bytes.
|
|
11
|
+
* commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
|
|
12
|
+
* the library's headerValueProblem rule (not blank, no control characters but tab,
|
|
13
|
+
* nothing above U+00FF), reported as a usage error.
|
|
17
14
|
*/
|
|
18
15
|
export declare function parseHeaderValue(value: string): string;
|
|
19
16
|
/**
|
|
@@ -27,14 +24,13 @@ export declare function parseHeaderValue(value: string): string;
|
|
|
27
24
|
export declare function parseOptionValue(value: string): string;
|
|
28
25
|
/** commander accumulator for a repeatable option whose values are checked by parseOptionValue. */
|
|
29
26
|
export declare function collectNonEmpty(value: string, previous?: string[]): string[];
|
|
30
|
-
/** Build a commander value-parser for a non-negative integer within [min, max]. */
|
|
27
|
+
/** Build a commander value-parser for a non-negative integer within [min, max] (the library's intRangeProblem). */
|
|
31
28
|
export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
|
|
32
29
|
/**
|
|
33
|
-
* commander value-parser for --base-url
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
* but this surfaces the mistake up front and independently of the transport.
|
|
30
|
+
* commander value-parser for --base-url (and CKAN_BASE_URL, via the preAction hook
|
|
31
|
+
* in program.ts): the library's baseUrlProblem rule (not blank, no whitespace, an
|
|
32
|
+
* absolute http(s) URL, no query string or fragment), reported as a usage error
|
|
33
|
+
* before the client is built.
|
|
38
34
|
*/
|
|
39
35
|
export declare function parseBaseUrl(value: string): string;
|
|
40
36
|
/** commander value-parser for --portal: the URL of a portal in the built-in list. */
|
|
@@ -77,4 +73,3 @@ export interface ActionContext {
|
|
|
77
73
|
* the trailing options object and command instance to recover the positionals.
|
|
78
74
|
*/
|
|
79
75
|
export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
|
|
80
|
-
//# sourceMappingURL=shared.d.ts.map
|
package/dist/src/cli/shared.js
CHANGED
|
@@ -4,6 +4,7 @@ import { InvalidArgumentError } from "commander";
|
|
|
4
4
|
import { isBidiControl } from "../client/engine.js";
|
|
5
5
|
import { CkanError } from "../client/errors.js";
|
|
6
6
|
import { findPortal } from "../client/portals.js";
|
|
7
|
+
import { baseUrlProblem, blankProblem, countProblem, headerValueProblem, intRangeProblem } from "../client/validate.js";
|
|
7
8
|
import { PORTALS } from "../client/portals-list.js";
|
|
8
9
|
/** commander value-parser: a non-negative integer. */
|
|
9
10
|
export function parseIntArg(value) {
|
|
@@ -14,41 +15,32 @@ export function parseIntArg(value) {
|
|
|
14
15
|
throw new InvalidArgumentError("Expected a non-negative integer.");
|
|
15
16
|
}
|
|
16
17
|
const n = Number(value);
|
|
17
|
-
//
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
// The library's count rule; it also rejects magnitudes that cannot be
|
|
19
|
+
// represented exactly (silent precision loss).
|
|
20
|
+
const reason = countProblem(n);
|
|
21
|
+
if (reason !== undefined)
|
|
22
|
+
throw new InvalidArgumentError(reason);
|
|
21
23
|
return n;
|
|
22
24
|
}
|
|
23
25
|
/**
|
|
24
|
-
* commander value-parser: a value that is not blank
|
|
25
|
-
*
|
|
26
|
+
* commander value-parser: a value that is not blank (the library's blankProblem
|
|
27
|
+
* rule, reported as a usage error before the client is built).
|
|
26
28
|
*/
|
|
27
29
|
export function parseNonEmpty(value) {
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
30
|
+
const reason = blankProblem(value);
|
|
31
|
+
if (reason !== undefined)
|
|
32
|
+
throw new InvalidArgumentError(reason);
|
|
31
33
|
return value;
|
|
32
34
|
}
|
|
33
35
|
/**
|
|
34
|
-
* commander value-parser for a value that ends up in an HTTP header (`--user-agent`)
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
* U+00FF, which surfaced as "Unexpected error". Reject those here as a usage error,
|
|
38
|
-
* along with a blank value. Tab is allowed, as in HTTP. Checked by char code so the
|
|
39
|
-
* source stays free of control bytes.
|
|
36
|
+
* commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
|
|
37
|
+
* the library's headerValueProblem rule (not blank, no control characters but tab,
|
|
38
|
+
* nothing above U+00FF), reported as a usage error.
|
|
40
39
|
*/
|
|
41
40
|
export function parseHeaderValue(value) {
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
if ((c < 0x20 && c !== 0x09) || c === 0x7f) {
|
|
46
|
-
throw new InvalidArgumentError("Value contains control characters.");
|
|
47
|
-
}
|
|
48
|
-
if (c > 0xff) {
|
|
49
|
-
throw new InvalidArgumentError("Value contains characters outside Latin-1 (above U+00FF).");
|
|
50
|
-
}
|
|
51
|
-
}
|
|
41
|
+
const reason = headerValueProblem(value);
|
|
42
|
+
if (reason !== undefined)
|
|
43
|
+
throw new InvalidArgumentError(reason);
|
|
52
44
|
return value;
|
|
53
45
|
}
|
|
54
46
|
/**
|
|
@@ -69,43 +61,27 @@ export function parseOptionValue(value) {
|
|
|
69
61
|
export function collectNonEmpty(value, previous = []) {
|
|
70
62
|
return previous.concat([parseOptionValue(value)]);
|
|
71
63
|
}
|
|
72
|
-
/** Build a commander value-parser for a non-negative integer within [min, max]. */
|
|
64
|
+
/** Build a commander value-parser for a non-negative integer within [min, max] (the library's intRangeProblem). */
|
|
73
65
|
export function parseBoundedInt(min, max) {
|
|
66
|
+
const problem = intRangeProblem(min, max);
|
|
74
67
|
return (value) => {
|
|
75
68
|
const n = parseIntArg(value);
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
throw new InvalidArgumentError(`Must be <= ${max}.`);
|
|
69
|
+
const reason = problem(n);
|
|
70
|
+
if (reason !== undefined)
|
|
71
|
+
throw new InvalidArgumentError(reason);
|
|
80
72
|
return n;
|
|
81
73
|
};
|
|
82
74
|
}
|
|
83
75
|
/**
|
|
84
|
-
* commander value-parser for --base-url
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
* but this surfaces the mistake up front and independently of the transport.
|
|
76
|
+
* commander value-parser for --base-url (and CKAN_BASE_URL, via the preAction hook
|
|
77
|
+
* in program.ts): the library's baseUrlProblem rule (not blank, no whitespace, an
|
|
78
|
+
* absolute http(s) URL, no query string or fragment), reported as a usage error
|
|
79
|
+
* before the client is built.
|
|
89
80
|
*/
|
|
90
81
|
export function parseBaseUrl(value) {
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
}
|
|
95
|
-
catch {
|
|
96
|
-
throw new InvalidArgumentError("Expected an absolute http(s) URL.");
|
|
97
|
-
}
|
|
98
|
-
if (url.protocol !== "http:" && url.protocol !== "https:") {
|
|
99
|
-
throw new InvalidArgumentError(`Unsupported scheme "${url.protocol}". Expected an http(s) URL.`);
|
|
100
|
-
}
|
|
101
|
-
if (/[?#]/.test(value)) {
|
|
102
|
-
throw new InvalidArgumentError("Expected a site URL without a query string or fragment.");
|
|
103
|
-
}
|
|
104
|
-
// `new URL` trims, but the value is used as given: a trailing space would land in
|
|
105
|
-
// the request path (`/404%20/api/3/...`) or the host.
|
|
106
|
-
if (value !== value.trim()) {
|
|
107
|
-
throw new InvalidArgumentError("A base URL cannot have surrounding whitespace.");
|
|
108
|
-
}
|
|
82
|
+
const reason = baseUrlProblem(value);
|
|
83
|
+
if (reason !== undefined)
|
|
84
|
+
throw new InvalidArgumentError(reason);
|
|
109
85
|
return value;
|
|
110
86
|
}
|
|
111
87
|
/** commander value-parser for --portal: the URL of a portal in the built-in list. */
|
|
@@ -194,4 +170,3 @@ export function action(deps, fn) {
|
|
|
194
170
|
await fn({ client, global, opts: command.opts() }, positionals);
|
|
195
171
|
};
|
|
196
172
|
}
|
|
197
|
-
//# sourceMappingURL=shared.js.map
|
|
@@ -4,8 +4,9 @@ import type { Group, GroupListParams, JsonValue, License, ListParams, Organizati
|
|
|
4
4
|
/**
|
|
5
5
|
* The site root of a CKAN instance, from what a user is likely to paste: portals
|
|
6
6
|
* document their API as `<site>/api/3/action`, so that suffix (or `/api/3`) is
|
|
7
|
-
* dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it.
|
|
8
|
-
*
|
|
7
|
+
* dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it.
|
|
8
|
+
* A base URL that breaks the rules of `validateBaseUrl` (blank, whitespace, not
|
|
9
|
+
* an http(s) URL, a query string or fragment) throws CkanValidationError.
|
|
9
10
|
*/
|
|
10
11
|
export declare function siteRoot(baseUrl: string): string;
|
|
11
12
|
export declare class CkanClient {
|
|
@@ -31,7 +32,8 @@ export declare class CkanClient {
|
|
|
31
32
|
* several as CKAN's `fq_list` (each its own Solr filter query; all must
|
|
32
33
|
* match). `fq_list` is only used for two or more, because CKAN splits a lone
|
|
33
34
|
* `fq_list` value into characters. Facet fields go out as the JSON list CKAN
|
|
34
|
-
* expects in `facet.field`.
|
|
35
|
+
* expects in `facet.field`. A blank `q`, `sort`, filter or facet field is
|
|
36
|
+
* refused (CkanValidationError), never sent or dropped.
|
|
35
37
|
*/
|
|
36
38
|
packageSearch(params?: PackageSearchParams): Promise<PackageSearchResult>;
|
|
37
39
|
/** A single dataset by id or name. */
|
|
@@ -42,7 +44,7 @@ export declare class CkanClient {
|
|
|
42
44
|
groupShow(id: string): Promise<Group>;
|
|
43
45
|
/** A single resource (distribution) by id. */
|
|
44
46
|
resourceShow(id: string): Promise<Resource>;
|
|
45
|
-
/** Dataset names, paged with limit/offset (a positive limit
|
|
47
|
+
/** Dataset names, paged with limit/offset (a positive limit, omit it for all; a non-negative offset). */
|
|
46
48
|
packageList(params?: ListParams): Promise<string[]>;
|
|
47
49
|
/**
|
|
48
50
|
* Organization names, or full objects with `all_fields`. See `groupOrOrgList`
|
|
@@ -51,7 +53,7 @@ export declare class CkanClient {
|
|
|
51
53
|
organizationList(params?: GroupListParams): Promise<JsonValue[]>;
|
|
52
54
|
/** Group names, or full objects with `all_fields` (paged like organizationList). */
|
|
53
55
|
groupList(params?: GroupListParams): Promise<JsonValue[]>;
|
|
54
|
-
/** Tags, optionally only those containing a substring. */
|
|
56
|
+
/** Tags, optionally only those containing a substring (a blank one is refused). */
|
|
55
57
|
tagList(params?: TagListParams): Promise<string[]>;
|
|
56
58
|
/** The licences this portal offers. */
|
|
57
59
|
licenseList(): Promise<License[]>;
|
|
@@ -74,4 +76,3 @@ export declare class CkanClient {
|
|
|
74
76
|
*/
|
|
75
77
|
private show;
|
|
76
78
|
}
|
|
77
|
-
//# sourceMappingURL=client.d.ts.map
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// CkanClient — a typed client over the open (no-auth) read endpoints of any CKAN
|
|
2
2
|
// Action API (`<site>/api/3/action`).
|
|
3
|
-
import { DEFAULT_BASE_URL, RequestEngine, sanitizeServerText } from "./engine.js";
|
|
4
|
-
import { CkanError, CkanParseError, describeCkanError, redactUrl } from "./errors.js";
|
|
3
|
+
import { DEFAULT_BASE_URL, RequestEngine, sanitizeServerText, validateBaseUrl } from "./engine.js";
|
|
4
|
+
import { CkanError, CkanParseError, CkanValidationError, describeCkanError, redactUrl } from "./errors.js";
|
|
5
|
+
import { assertValid, blankProblem, countProblem, facetLimitProblem } from "./validate.js";
|
|
5
6
|
const ACTION = "/api/3/action";
|
|
6
7
|
/**
|
|
7
8
|
* CKAN action names are always `[a-z0-9_]+`. Restricting to that allowlist closes
|
|
@@ -22,18 +23,20 @@ function entryKey(entry) {
|
|
|
22
23
|
return JSON.stringify(entry);
|
|
23
24
|
}
|
|
24
25
|
/**
|
|
25
|
-
* Drop undefined
|
|
26
|
-
*
|
|
27
|
-
*
|
|
26
|
+
* Drop undefined values so only the parameters the caller actually set are sent,
|
|
27
|
+
* and refuse a blank parameter name, a blank value or a list with a blank entry
|
|
28
|
+
* (CkanValidationError). CKAN reads an empty parameter as "not given", so a blank
|
|
29
|
+
* filter such as `tagList({ query: "" })` would silently return everything.
|
|
28
30
|
*/
|
|
29
31
|
function prune(params) {
|
|
30
32
|
// A null-prototype object, so a `__proto__` key is kept as a parameter instead
|
|
31
33
|
// of setting the prototype (and being lost).
|
|
32
34
|
const out = Object.create(null);
|
|
33
35
|
for (const [k, v] of Object.entries(params)) {
|
|
34
|
-
if (v === undefined
|
|
36
|
+
if (v === undefined)
|
|
35
37
|
continue;
|
|
36
|
-
|
|
38
|
+
assertValid("parameter name", k, blankProblem);
|
|
39
|
+
out[k] = assertValid(k, v, blankProblem);
|
|
37
40
|
}
|
|
38
41
|
return out;
|
|
39
42
|
}
|
|
@@ -62,22 +65,24 @@ function assertLimit(limit) {
|
|
|
62
65
|
if (limit === undefined)
|
|
63
66
|
return;
|
|
64
67
|
if (!Number.isSafeInteger(limit) || limit < 1) {
|
|
65
|
-
throw new
|
|
68
|
+
throw new CkanValidationError(`Invalid limit: expected a positive integer, got ${String(limit)}. Leave it out for the whole list.`);
|
|
66
69
|
}
|
|
67
70
|
}
|
|
71
|
+
/** Check an optional count or offset (`rows`, `start`, `offset`): see countProblem. */
|
|
72
|
+
function assertCount(name, value) {
|
|
73
|
+
if (value !== undefined)
|
|
74
|
+
assertValid(name, value, countProblem);
|
|
75
|
+
}
|
|
68
76
|
/**
|
|
69
77
|
* The site root of a CKAN instance, from what a user is likely to paste: portals
|
|
70
78
|
* document their API as `<site>/api/3/action`, so that suffix (or `/api/3`) is
|
|
71
|
-
* dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it.
|
|
72
|
-
*
|
|
79
|
+
* dropped. A CKAN mounted under a sub-path (`https://host/ckan`) keeps it.
|
|
80
|
+
* A base URL that breaks the rules of `validateBaseUrl` (blank, whitespace, not
|
|
81
|
+
* an http(s) URL, a query string or fragment) throws CkanValidationError.
|
|
73
82
|
*/
|
|
74
83
|
export function siteRoot(baseUrl) {
|
|
75
|
-
//
|
|
76
|
-
|
|
77
|
-
if (/[?#]/.test(baseUrl)) {
|
|
78
|
-
throw new CkanError(`The base URL must not contain a query string or fragment: ${redactUrl(baseUrl)}`);
|
|
79
|
-
}
|
|
80
|
-
return baseUrl.replace(/\/+$/, "").replace(/\/api\/3(\/action)?$/, "");
|
|
84
|
+
// Checked before the suffix strip: a trailing space would hide the suffix from it.
|
|
85
|
+
return validateBaseUrl(baseUrl).replace(/\/api\/3(\/action)?$/, "");
|
|
81
86
|
}
|
|
82
87
|
export class CkanClient {
|
|
83
88
|
engine;
|
|
@@ -132,10 +137,19 @@ export class CkanClient {
|
|
|
132
137
|
* several as CKAN's `fq_list` (each its own Solr filter query; all must
|
|
133
138
|
* match). `fq_list` is only used for two or more, because CKAN splits a lone
|
|
134
139
|
* `fq_list` value into characters. Facet fields go out as the JSON list CKAN
|
|
135
|
-
* expects in `facet.field`.
|
|
140
|
+
* expects in `facet.field`. A blank `q`, `sort`, filter or facet field is
|
|
141
|
+
* refused (CkanValidationError), never sent or dropped.
|
|
136
142
|
*/
|
|
137
|
-
packageSearch(params = {}) {
|
|
138
|
-
|
|
143
|
+
async packageSearch(params = {}) {
|
|
144
|
+
assertValid("q", params.q, blankProblem);
|
|
145
|
+
assertValid("fq", params.fq, blankProblem);
|
|
146
|
+
assertValid("sort", params.sort, blankProblem);
|
|
147
|
+
assertValid("facet_field", params.facet_field, blankProblem);
|
|
148
|
+
assertCount("rows", params.rows);
|
|
149
|
+
assertCount("start", params.start);
|
|
150
|
+
if (params.facet_limit !== undefined)
|
|
151
|
+
assertValid("facet_limit", params.facet_limit, facetLimitProblem);
|
|
152
|
+
const fq = params.fq ?? [];
|
|
139
153
|
const facetFields = params.facet_field ?? [];
|
|
140
154
|
return this.typed("package_search", {
|
|
141
155
|
q: params.q,
|
|
@@ -164,9 +178,10 @@ export class CkanClient {
|
|
|
164
178
|
resourceShow(id) {
|
|
165
179
|
return this.show("resource_show", id);
|
|
166
180
|
}
|
|
167
|
-
/** Dataset names, paged with limit/offset (a positive limit
|
|
181
|
+
/** Dataset names, paged with limit/offset (a positive limit, omit it for all; a non-negative offset). */
|
|
168
182
|
async packageList(params = {}) {
|
|
169
183
|
assertLimit(params.limit);
|
|
184
|
+
assertCount("offset", params.offset);
|
|
170
185
|
return this.typed("package_list", { limit: params.limit, offset: params.offset }, Array.isArray, "an array");
|
|
171
186
|
}
|
|
172
187
|
/**
|
|
@@ -180,7 +195,7 @@ export class CkanClient {
|
|
|
180
195
|
groupList(params = {}) {
|
|
181
196
|
return this.groupOrOrgList("group_list", params);
|
|
182
197
|
}
|
|
183
|
-
/** Tags, optionally only those containing a substring. */
|
|
198
|
+
/** Tags, optionally only those containing a substring (a blank one is refused). */
|
|
184
199
|
tagList(params = {}) {
|
|
185
200
|
return this.typed("tag_list", { query: params.query }, Array.isArray, "an array");
|
|
186
201
|
}
|
|
@@ -202,6 +217,8 @@ export class CkanClient {
|
|
|
202
217
|
*/
|
|
203
218
|
async groupOrOrgList(action, params) {
|
|
204
219
|
assertLimit(params.limit);
|
|
220
|
+
// Before the first request, and before the all_fields pager steps on from it.
|
|
221
|
+
assertCount("offset", params.offset);
|
|
205
222
|
if (!params.all_fields) {
|
|
206
223
|
return this.typed(action, { limit: params.limit, offset: params.offset }, Array.isArray, "an array");
|
|
207
224
|
}
|
|
@@ -240,4 +257,3 @@ export class CkanClient {
|
|
|
240
257
|
return this.typed(action, { id }, isObject, "a JSON object");
|
|
241
258
|
}
|
|
242
259
|
}
|
|
243
|
-
//# sourceMappingURL=client.js.map
|
|
@@ -13,30 +13,44 @@ export interface EngineOptions {
|
|
|
13
13
|
baseUrl?: string;
|
|
14
14
|
/** Swappable transport. Defaults to the built-in node http/https transport. */
|
|
15
15
|
transport?: Transport;
|
|
16
|
-
/**
|
|
16
|
+
/**
|
|
17
|
+
* Value of the User-Agent header. Must be sendable (see `assertHeaderValue`):
|
|
18
|
+
* not blank, no control characters but tab, nothing above U+00FF.
|
|
19
|
+
*/
|
|
17
20
|
userAgent?: string;
|
|
18
|
-
/** Per-request timeout in milliseconds
|
|
21
|
+
/** Per-request timeout in milliseconds, 0 to `MAX_TIMEOUT_MS` (2^31 - 1 ms); 0 disables. */
|
|
19
22
|
timeoutMs?: number;
|
|
20
23
|
/**
|
|
21
24
|
* Number of automatic retries for transient (429/503) responses. Each waits the
|
|
22
25
|
* response's `Retry-After` (up to `MAX_RETRY_AFTER_MS`; a longer one is not
|
|
23
|
-
* retried), or else `retryDelayMs * attempt`.
|
|
26
|
+
* retried), or else `retryDelayMs * attempt`. 0 to `MAX_RETRIES`; defaults to 2.
|
|
24
27
|
*/
|
|
25
28
|
maxRetries?: number;
|
|
26
29
|
/** Base backoff between retries in milliseconds (grows linearly); used without a Retry-After. */
|
|
27
30
|
retryDelayMs?: number;
|
|
28
|
-
/** Number of HTTP redirects (301/302/303/307/308) to follow
|
|
31
|
+
/** Number of HTTP redirects (301/302/303/307/308) to follow, 0 to `MAX_REDIRECTS`. Defaults to 5. */
|
|
29
32
|
maxRedirects?: number;
|
|
30
33
|
/**
|
|
31
34
|
* Hard cap on response body size in bytes (defends against memory exhaustion
|
|
32
35
|
* from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit.
|
|
36
|
+
*
|
|
37
|
+
* Every numeric option must be a non-negative safe integer within its range;
|
|
38
|
+
* the constructor throws CkanValidationError otherwise (a negative or NaN
|
|
39
|
+
* timeout or cap would silently switch that guard off).
|
|
33
40
|
*/
|
|
34
41
|
maxResponseBytes?: number;
|
|
35
42
|
/** Injectable sleep, primarily for deterministic tests. */
|
|
36
43
|
sleep?: (ms: number) => Promise<void>;
|
|
37
44
|
}
|
|
38
|
-
/** Most automatic retries the CLI's --max-retries
|
|
45
|
+
/** Most automatic retries the engine performs (`maxRetries`, the CLI's --max-retries). */
|
|
39
46
|
export declare const MAX_RETRIES = 10;
|
|
47
|
+
/** Most redirects the engine follows (`maxRedirects`). */
|
|
48
|
+
export declare const MAX_REDIRECTS = 10;
|
|
49
|
+
/**
|
|
50
|
+
* Check a value for an HTTP header (headerValueProblem) and return it, or throw
|
|
51
|
+
* CkanValidationError `Invalid <name>: …`.
|
|
52
|
+
*/
|
|
53
|
+
export declare function assertHeaderValue(name: string, value: string): string;
|
|
40
54
|
/**
|
|
41
55
|
* Longest `Retry-After` the engine waits out before retrying a 429/503. When the
|
|
42
56
|
* server asks for longer, the engine does not retry at all and surfaces the error at
|
|
@@ -82,6 +96,15 @@ export declare function isBidiControl(code: number): boolean;
|
|
|
82
96
|
* Written as a char-code filter so no raw control byte appears in this source.
|
|
83
97
|
*/
|
|
84
98
|
export declare function sanitizeServerText(text: string): string;
|
|
99
|
+
/**
|
|
100
|
+
* Check a base URL (baseUrlProblem: not blank, no whitespace or control
|
|
101
|
+
* characters, an absolute http(s) URL, no query string or fragment) and return it
|
|
102
|
+
* without trailing slashes. Throws CkanValidationError `Invalid base URL: …` — a
|
|
103
|
+
* configuration mistake, not a CkanNetworkError. The RequestEngine and CkanClient
|
|
104
|
+
* constructors call it, so a custom transport never sees a bad base URL; the
|
|
105
|
+
* default transport still re-checks the scheme on every hop.
|
|
106
|
+
*/
|
|
107
|
+
export declare function validateBaseUrl(raw: string): string;
|
|
85
108
|
export declare class RequestEngine {
|
|
86
109
|
private readonly baseUrl;
|
|
87
110
|
private readonly transport;
|
|
@@ -104,4 +127,3 @@ export declare class RequestEngine {
|
|
|
104
127
|
getJson<T>(path: string, query?: QueryParams): Promise<T>;
|
|
105
128
|
private toApiError;
|
|
106
129
|
}
|
|
107
|
-
//# sourceMappingURL=engine.d.ts.map
|