This commit is contained in:
Christian Fraß 2023-06-19 13:05:17 +02:00
parent 4dbb7474e7
commit fc3d99e3a1
27 changed files with 1865 additions and 1595 deletions

View file

@ -383,6 +383,443 @@ declare namespace lib_plankton.base {
*/ */
function object_merge(core: Record<string, any>, mantle: Record<string, any>): Record<string, any>; function object_merge(core: Record<string, any>, mantle: Record<string, any>): Record<string, any>;
} }
declare namespace lib_plankton.call {
/**
* @desc hacked class for postfix function application
* @author fenris
*/
class class_valuewrapper<type_value> {
/**
* @author fenris
*/
protected value: type_value;
/**
* @desc [constructor]
* @author fenris
*/
constructor(value: type_value);
/**
* @desc [accessor] applies a function and returns a new valuewrapper
* @author fenris
*/
pass<type_value_>(function_: (value: type_value) => type_value_): class_valuewrapper<type_value_>;
/**
* @desc [accessor] gives the wrapped value
* @author fenris
*/
extract(): type_value;
}
/**
* @desc shortcut for constructing a valuewrapper-object
* @author fenris
*/
function vw<type_value>(value: type_value): class_valuewrapper<type_value>;
/**
* @author fenris
*/
function use<type_input, type_output>(input: type_input, function_: (input: type_input) => type_output): type_output;
/**
* @desc just the identity; useful for some callbacks etc.
* @author fenris
*/
function id<type_value>(x: type_value): type_value;
/**
* @desc composes two functions (i.e. returns a function that return the result of the successive execution of both input-functions)
* @param {function} function_f
* @param {function} function_g
* @author fenris
*/
function compose<type_x, type_y, type_z>(function_f: (type_x: any) => type_y, function_g: (type_y: any) => type_z): (value: type_x) => type_z;
/**
* @desc transforms a function with sequential input into a function with leveled input; example: add(2,3) = curryfy(add)(2)(3)
* @param {function} f
* @param {int} n (don't set manually)
* @return {function} the currified version of the in put function
* @author fenris
*/
function curryfy(f: Function, n?: int): Function;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_executor<type_result, type_reason> = ((resolve: (result?: type_result) => any, reject?: (reason?: type_reason) => void) => void);
/**
* @author fenris
*/
function executor_resolve<type_result, type_reason>(result: type_result): type_executor<type_result, type_reason>;
/**
* @author fenris
*/
function executor_reject<type_result, type_reason>(reason: type_reason): type_executor<type_result, type_reason>;
/**
* @author fenris
*/
function executor_transform<type_result_from, type_error_from, type_result_to, type_error_to>(executor: type_executor<type_result_from, type_error_from>, transform_result: (result_from: type_result_from) => type_result_to, transform_reason: (error_from: type_error_from) => type_error_to): type_executor<type_result_to, type_error_to>;
/**
* @author fenris
*/
function executor_transform_default<type_result_from, type_result_to>(executor: type_executor<type_result_from, Error>, transform_result: (result_from: type_result_from) => type_result_to, wrap_string?: string): type_executor<type_result_to, Error>;
/**
* @author fenris
*/
function executor_compose_sequential<type_result_first, type_result_second, type_reason>(first: type_executor<type_result_first, type_reason>, second: (result: type_result_first) => type_executor<type_result_second, type_reason>): type_executor<type_result_second, type_reason>;
/**
* @author fenris
*/
function executor_chain<type_state, type_error>(state: type_state, executors: Array<(state: type_state) => type_executor<type_state, type_error>>): type_executor<type_state, type_error>;
/**
* @author fenris
*/
function executor_first<type_result, type_reason>(executors: Array<type_executor<type_result, type_reason>>): type_executor<type_result, Array<type_reason>>;
/**
* @author fenris
*/
function executor_condense<type_element>(executors: Array<type_executor<type_element, Error>>): type_executor<Array<type_element>, Error>;
/**
* @author fenris
* @deprecated use condense
*/
function executor_filter<type_element>(executors: Array<type_executor<type_element, Error>>, predicate: (element: type_element) => boolean): type_executor<Array<type_element>, Error>;
/**
* @author fenris
* @deprecated use condense
*/
function executor_map<type_element1, type_element2>(executors: Array<type_executor<type_element1, Error>>, transformator: (element1: type_element1) => type_element2): type_executor<Array<type_element2>, Error>;
/**
* @author fenris
* @deprecated use condense
*/
function executor_reduce<type_element, type_result>(executors: Array<type_executor<type_element, Error>>, initial: type_result, accumulator: (result: type_result, element: type_element) => type_result): type_executor<type_result, Error>;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_promise<type_result, type_reason> = Promise<type_result>;
/**
* @author fenris
*/
function promise_reject<type_result, type_reason>(reason: type_reason): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_resolve<type_result, type_reason>(result: type_result): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_make<type_result, type_reason>(executor: (resolve: (result?: type_result) => void, reject: (reason?: type_reason) => void) => void): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_then_close<type_result, type_reason>(promise: type_promise<type_result, type_reason>, resolver: (result: type_result) => void, rejector: (reason: type_reason) => void): void;
/**
* @author fenris
*/
function promise_then_append<type_result, type_reason, type_result_>(promise: type_promise<type_result, type_reason>, resolver: (result: type_result) => type_promise<type_result_, type_reason>, rejector?: (reason: type_reason) => type_promise<type_result_, type_reason>): type_promise<type_result_, type_result>;
/**
* @author fenris
*/
function promise_all<type_result, type_reason>(promises: Array<type_promise<type_result, type_reason>>): type_promise<Array<type_result>, type_reason>;
/**
* @author fenris
*/
function promise_chain<type_result, type_reason>(promises: Array<(input: type_result) => type_promise<type_result, type_reason>>, start?: type_result): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_condense<type_element, type_reason>(promises: Array<() => type_promise<type_element, type_reason>>): type_promise<Array<type_element>, type_reason>;
/**
* @author fenris
*/
function promise_group<type_reason>(promises: {
[name: string]: () => type_promise<any, type_reason>;
}, serial?: boolean): type_promise<{
[name: string]: any;
}, type_reason>;
/**
* @author fenris
*/
function promise_wrap<type_result_inner, type_result_outer, type_reason>(promise: type_promise<type_result_inner, type_reason>, transformator_result: (reason: type_result_inner) => type_result_outer, transformator_reason?: (reason: type_reason) => type_reason): type_promise<type_result_outer, type_reason>;
/**
* @author fenris
*/
function promise_show<type_result, type_reason>(label: string): (result: type_result) => type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_log<type_result, type_reason>(result: type_result): (result: type_result) => type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_attach<type_reason>(state: {
[name: string]: any;
}, promise: type_promise<any, type_reason>, name: string): type_promise<{
[name: string]: any;
}, type_reason>;
/**
* @author fenris
*/
function promise_delay<type_result, type_reason>(promise: type_promise<type_result, type_reason>, delay: int): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_to_executor<type_result, type_reason>(promise: type_promise<type_result, type_reason>): type_executor<type_result, type_reason>;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_initializer_state = int;
const initializer_state_initial: type_initializer_state;
const initializer_state_waiting: type_initializer_state;
const initializer_state_successful: type_initializer_state;
const initializer_state_failed: type_initializer_state;
/**
* @author fenris
*/
type type_initializer<type_result, type_reason> = {
fetcher: () => type_promise<type_result, type_reason>;
state?: type_initializer_state;
queue: Array<{
resolve: (result?: type_result) => void;
reject: (reason?: type_reason) => void;
}>;
result?: type_result;
reason?: type_reason;
};
/**
* @author fenris
*/
function initializer_make<type_result, type_reason>(fetcher: () => type_promise<type_result, type_reason>): type_initializer<type_result, type_reason>;
/**
* @author fenris
*/
function initializer_reset<type_result, type_reason>(subject: type_initializer<type_result, type_reason>): void;
/**
* @author fenris
*/
function initializer_state<type_result, type_reason>(subject: type_initializer<type_result, type_reason>): type_initializer_state;
/**
* @author fenris
*/
function initializer_get<type_result, type_reason>(subject: type_initializer<type_result, type_reason>): type_promise<type_result, type_reason>;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_deferral<type_input, type_output> = {
representation: (input: type_input) => Promise<type_output>;
};
/**
* @author fenris
* @desc activates the deferral and handles its output according to a given procedure
* @param {(value : type_value)=>void} procedure a function which receives the output of the deferral as argument
*/
function deferral_use<type_input, type_output>(deferral: type_deferral<type_input, type_output>, input: type_input, procedure: (output: type_output) => void): void;
/**
* @author fenris
* @desc creates a deferral-subject (similar to "new Promise", where "convey" reflects "resolve"/"reject")
*/
function deferral_make<type_input, type_output>(handler: (input: type_input, convey: (output: type_output) => void) => void): type_deferral<type_input, type_output>;
/**
* @author fenris
* @desc wraps a simple function into a deferral (similar to "Promise.resolve"/"Promise.reject")
*/
function deferral_wrap<type_input, type_output>(function_: (input: type_input) => type_output): type_deferral<type_input, type_output>;
/**
* @author fenris
*/
function deferral_id<type_value>(): type_deferral<type_value, type_value>;
/**
* @author fenris
*/
function deferral_const<type_value>(value: type_value): type_deferral<type_value, type_value>;
/**
* @author fenris
*/
function deferral_delay<type_output>(output: type_output, delay: int): type_deferral<any, type_output>;
/**
* @author fenris
* @desc connects two deferrals to form a new one; the output of the first is taken as input for the second
* (similar to "Promise.then" when passing a function which returns a new promise)
* @param {type_deferral<type_value1>} first a simple deferral
* @param {(value1 : type_value1)=>type_deferral<type_value2>} second a function depending from a value returning a deferral
*/
function deferral_compose_serial<type_input, type_between, type_output>(first: type_deferral<type_input, type_between>, second: type_deferral<type_between, type_output>): type_deferral<type_input, type_output>;
/**
* @author fenris
*/
function deferral_compose_parallel<type_input, type_output_left, type_output_right>({ "left": deferral_left, "right": deferral_right, }: {
left: type_deferral<type_input, type_output_left>;
right: type_deferral<type_input, type_output_right>;
}): type_deferral<type_input, {
left: type_output_left;
right: type_output_right;
}>;
/**
* @author fenris
* @desc repeatedly applied serial composition
*/
function deferral_chain<type_value>(members: Array<type_deferral<type_value, type_value>>): type_deferral<type_value, type_value>;
/**
* @author fenris
*/
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
class class_deferral<type_input, type_output> {
/**
* @author fenris
*/
private subject;
/**
* @author fenris
*/
private constructor();
/**
* @author fenris
*/
private static _cram;
/**
* @author fenris
*/
private static _tear;
/**
* @author fenris
*/
static make<type_input, type_output>(handler: (input: type_input, convey: (value: type_output) => void) => void): class_deferral<type_input, type_output>;
/**
* @author fenris
*/
use(input: type_input, procedure: (value: type_output) => void): void;
/**
* @author fenris
*/
compose_serial<type_output_>(second: class_deferral<type_output, type_output_>): class_deferral<type_input, type_output_>;
/**
* @author fenris
*/
static chain<type_value>(members: Array<class_deferral<type_value, type_value>>): class_deferral<type_value, type_value>;
/**
* @author fenris
*/
static wrap<type_input, type_output>(function_: (input: type_input) => type_output): class_deferral<type_input, type_output>;
/**
* @author fenris
*/
static const_<type_value>(value: type_value): class_deferral<type_value, type_value>;
/**
* @author fenris
*/
static delay<type_output>(output: type_output, delay: int): class_deferral<any, type_output>;
}
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
function convey(value: any, functions: Array<Function>): any;
/**
* @author fenris
*/
function timeout(function_: () => void, delay: int): int;
/**
* @desc a definition for a value being "defined"
* @author neuc
*/
function is_def<type_value>(obj: type_value, null_is_valid?: boolean): boolean;
/**
* @desc returns the value if set and, when a type is specified, if the type is correct, if not return default_value
* @author neuc
*/
function def_val(value: any, default_value: any, type?: string, null_is_valid?: boolean): any;
/**
* @desc just the empty function; useful for some callbacks etc.
* @author fenris
*/
function nothing(): void;
/**
* @desc outputs
* @author fenris
*/
/**
* @desc converts the "arguments"-map into an array
* @param {Object} args
* @author fenris
*/
function args2list(args: any): Array<any>;
/**
* @desc provides the call for an attribute of a class as a regular function
* @param {string} name the name of the attribute
* @return {*}
* @author fenris
*/
function attribute<type_object, type_attribute>(name: string): (object: type_object) => type_attribute;
/**
* @desc provides a method of a class as a regular function
* @param {string} name the name of the method
* @return {function}
* @author fenris
*/
function method<type_object, type_output>(name: string): (object: type_object) => type_output;
/**
* @author fenris
*/
type type_unival = {
kind: string;
data?: any;
};
/**
* @author fenris
*/
function distinguish(unival: type_unival, handlers: {
[kind: string]: (data?: any) => any;
}, fallback?: (unival?: type_unival) => any): any;
/**
* Promise version of "setTimeout"
*
* @author fenris
*/
function defer<type_result>(seconds: int, action: (() => type_result)): Promise<type_result>;
/**
* for rate_limit_check
*
* @author fenris
*/
type type_mana_snapshot = {
timestamp: float;
value: float;
};
/**
* rate limiting algorithm, based on the idea of mana (magic power) in video games:
* - an actor has a fixed mana capacity, i.e. the maximum amount of available power
* - an actor has a fixed rate of mana regeneration, i.e. how fast the power is filled up (linear growth)
* - an action has a defined mana heft, i.e. how much power is required and deducted in order to execute it
* - mana states are represented by snapshots, i.e. the amount of power at a certain point in time
*
* @author fenris
*/
function rate_limit_check(setup: {
capacity: float;
regeneration_rate: float;
get_snapshot: (() => Promise<(null | type_mana_snapshot)>);
set_snapshot: ((snapshot: type_mana_snapshot) => Promise<void>);
update_snapshot: ((timestamp: float, value_increment: float) => Promise<void>);
}, heft: float): Promise<{
granted: boolean;
seconds: (null | float);
}>;
}
declare namespace lib_plankton.sha256 {
/**
* @author fenris
*/
function get(value: string, secret?: string): string;
}
declare namespace lib_plankton.log { declare namespace lib_plankton.log {
/** /**
*/ */
@ -1037,433 +1474,6 @@ declare namespace lib_plankton.object {
*/ */
function copy(object: Object): Object; function copy(object: Object): Object;
} }
declare namespace lib_plankton.call {
/**
* @desc hacked class for postfix function application
* @author fenris
*/
class class_valuewrapper<type_value> {
/**
* @author fenris
*/
protected value: type_value;
/**
* @desc [constructor]
* @author fenris
*/
constructor(value: type_value);
/**
* @desc [accessor] applies a function and returns a new valuewrapper
* @author fenris
*/
pass<type_value_>(function_: (value: type_value) => type_value_): class_valuewrapper<type_value_>;
/**
* @desc [accessor] gives the wrapped value
* @author fenris
*/
extract(): type_value;
}
/**
* @desc shortcut for constructing a valuewrapper-object
* @author fenris
*/
function vw<type_value>(value: type_value): class_valuewrapper<type_value>;
/**
* @author fenris
*/
function use<type_input, type_output>(input: type_input, function_: (input: type_input) => type_output): type_output;
/**
* @desc just the identity; useful for some callbacks etc.
* @author fenris
*/
function id<type_value>(x: type_value): type_value;
/**
* @desc composes two functions (i.e. returns a function that return the result of the successive execution of both input-functions)
* @param {function} function_f
* @param {function} function_g
* @author fenris
*/
function compose<type_x, type_y, type_z>(function_f: (type_x: any) => type_y, function_g: (type_y: any) => type_z): (value: type_x) => type_z;
/**
* @desc transforms a function with sequential input into a function with leveled input; example: add(2,3) = curryfy(add)(2)(3)
* @param {function} f
* @param {int} n (don't set manually)
* @return {function} the currified version of the in put function
* @author fenris
*/
function curryfy(f: Function, n?: int): Function;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_executor<type_result, type_reason> = ((resolve: (result?: type_result) => any, reject?: (reason?: type_reason) => void) => void);
/**
* @author fenris
*/
function executor_resolve<type_result, type_reason>(result: type_result): type_executor<type_result, type_reason>;
/**
* @author fenris
*/
function executor_reject<type_result, type_reason>(reason: type_reason): type_executor<type_result, type_reason>;
/**
* @author fenris
*/
function executor_transform<type_result_from, type_error_from, type_result_to, type_error_to>(executor: type_executor<type_result_from, type_error_from>, transform_result: (result_from: type_result_from) => type_result_to, transform_reason: (error_from: type_error_from) => type_error_to): type_executor<type_result_to, type_error_to>;
/**
* @author fenris
*/
function executor_transform_default<type_result_from, type_result_to>(executor: type_executor<type_result_from, Error>, transform_result: (result_from: type_result_from) => type_result_to, wrap_string?: string): type_executor<type_result_to, Error>;
/**
* @author fenris
*/
function executor_compose_sequential<type_result_first, type_result_second, type_reason>(first: type_executor<type_result_first, type_reason>, second: (result: type_result_first) => type_executor<type_result_second, type_reason>): type_executor<type_result_second, type_reason>;
/**
* @author fenris
*/
function executor_chain<type_state, type_error>(state: type_state, executors: Array<(state: type_state) => type_executor<type_state, type_error>>): type_executor<type_state, type_error>;
/**
* @author fenris
*/
function executor_first<type_result, type_reason>(executors: Array<type_executor<type_result, type_reason>>): type_executor<type_result, Array<type_reason>>;
/**
* @author fenris
*/
function executor_condense<type_element>(executors: Array<type_executor<type_element, Error>>): type_executor<Array<type_element>, Error>;
/**
* @author fenris
* @deprecated use condense
*/
function executor_filter<type_element>(executors: Array<type_executor<type_element, Error>>, predicate: (element: type_element) => boolean): type_executor<Array<type_element>, Error>;
/**
* @author fenris
* @deprecated use condense
*/
function executor_map<type_element1, type_element2>(executors: Array<type_executor<type_element1, Error>>, transformator: (element1: type_element1) => type_element2): type_executor<Array<type_element2>, Error>;
/**
* @author fenris
* @deprecated use condense
*/
function executor_reduce<type_element, type_result>(executors: Array<type_executor<type_element, Error>>, initial: type_result, accumulator: (result: type_result, element: type_element) => type_result): type_executor<type_result, Error>;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_promise<type_result, type_reason> = Promise<type_result>;
/**
* @author fenris
*/
function promise_reject<type_result, type_reason>(reason: type_reason): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_resolve<type_result, type_reason>(result: type_result): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_make<type_result, type_reason>(executor: (resolve: (result?: type_result) => void, reject: (reason?: type_reason) => void) => void): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_then_close<type_result, type_reason>(promise: type_promise<type_result, type_reason>, resolver: (result: type_result) => void, rejector: (reason: type_reason) => void): void;
/**
* @author fenris
*/
function promise_then_append<type_result, type_reason, type_result_>(promise: type_promise<type_result, type_reason>, resolver: (result: type_result) => type_promise<type_result_, type_reason>, rejector?: (reason: type_reason) => type_promise<type_result_, type_reason>): type_promise<type_result_, type_result>;
/**
* @author fenris
*/
function promise_all<type_result, type_reason>(promises: Array<type_promise<type_result, type_reason>>): type_promise<Array<type_result>, type_reason>;
/**
* @author fenris
*/
function promise_chain<type_result, type_reason>(promises: Array<(input: type_result) => type_promise<type_result, type_reason>>, start?: type_result): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_condense<type_element, type_reason>(promises: Array<() => type_promise<type_element, type_reason>>): type_promise<Array<type_element>, type_reason>;
/**
* @author fenris
*/
function promise_group<type_reason>(promises: {
[name: string]: () => type_promise<any, type_reason>;
}, serial?: boolean): type_promise<{
[name: string]: any;
}, type_reason>;
/**
* @author fenris
*/
function promise_wrap<type_result_inner, type_result_outer, type_reason>(promise: type_promise<type_result_inner, type_reason>, transformator_result: (reason: type_result_inner) => type_result_outer, transformator_reason?: (reason: type_reason) => type_reason): type_promise<type_result_outer, type_reason>;
/**
* @author fenris
*/
function promise_show<type_result, type_reason>(label: string): (result: type_result) => type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_log<type_result, type_reason>(result: type_result): (result: type_result) => type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_attach<type_reason>(state: {
[name: string]: any;
}, promise: type_promise<any, type_reason>, name: string): type_promise<{
[name: string]: any;
}, type_reason>;
/**
* @author fenris
*/
function promise_delay<type_result, type_reason>(promise: type_promise<type_result, type_reason>, delay: int): type_promise<type_result, type_reason>;
/**
* @author fenris
*/
function promise_to_executor<type_result, type_reason>(promise: type_promise<type_result, type_reason>): type_executor<type_result, type_reason>;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_initializer_state = int;
const initializer_state_initial: type_initializer_state;
const initializer_state_waiting: type_initializer_state;
const initializer_state_successful: type_initializer_state;
const initializer_state_failed: type_initializer_state;
/**
* @author fenris
*/
type type_initializer<type_result, type_reason> = {
fetcher: () => type_promise<type_result, type_reason>;
state?: type_initializer_state;
queue: Array<{
resolve: (result?: type_result) => void;
reject: (reason?: type_reason) => void;
}>;
result?: type_result;
reason?: type_reason;
};
/**
* @author fenris
*/
function initializer_make<type_result, type_reason>(fetcher: () => type_promise<type_result, type_reason>): type_initializer<type_result, type_reason>;
/**
* @author fenris
*/
function initializer_reset<type_result, type_reason>(subject: type_initializer<type_result, type_reason>): void;
/**
* @author fenris
*/
function initializer_state<type_result, type_reason>(subject: type_initializer<type_result, type_reason>): type_initializer_state;
/**
* @author fenris
*/
function initializer_get<type_result, type_reason>(subject: type_initializer<type_result, type_reason>): type_promise<type_result, type_reason>;
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
type type_deferral<type_input, type_output> = {
representation: (input: type_input) => Promise<type_output>;
};
/**
* @author fenris
* @desc activates the deferral and handles its output according to a given procedure
* @param {(value : type_value)=>void} procedure a function which receives the output of the deferral as argument
*/
function deferral_use<type_input, type_output>(deferral: type_deferral<type_input, type_output>, input: type_input, procedure: (output: type_output) => void): void;
/**
* @author fenris
* @desc creates a deferral-subject (similar to "new Promise", where "convey" reflects "resolve"/"reject")
*/
function deferral_make<type_input, type_output>(handler: (input: type_input, convey: (output: type_output) => void) => void): type_deferral<type_input, type_output>;
/**
* @author fenris
* @desc wraps a simple function into a deferral (similar to "Promise.resolve"/"Promise.reject")
*/
function deferral_wrap<type_input, type_output>(function_: (input: type_input) => type_output): type_deferral<type_input, type_output>;
/**
* @author fenris
*/
function deferral_id<type_value>(): type_deferral<type_value, type_value>;
/**
* @author fenris
*/
function deferral_const<type_value>(value: type_value): type_deferral<type_value, type_value>;
/**
* @author fenris
*/
function deferral_delay<type_output>(output: type_output, delay: int): type_deferral<any, type_output>;
/**
* @author fenris
* @desc connects two deferrals to form a new one; the output of the first is taken as input for the second
* (similar to "Promise.then" when passing a function which returns a new promise)
* @param {type_deferral<type_value1>} first a simple deferral
* @param {(value1 : type_value1)=>type_deferral<type_value2>} second a function depending from a value returning a deferral
*/
function deferral_compose_serial<type_input, type_between, type_output>(first: type_deferral<type_input, type_between>, second: type_deferral<type_between, type_output>): type_deferral<type_input, type_output>;
/**
* @author fenris
*/
function deferral_compose_parallel<type_input, type_output_left, type_output_right>({ "left": deferral_left, "right": deferral_right, }: {
left: type_deferral<type_input, type_output_left>;
right: type_deferral<type_input, type_output_right>;
}): type_deferral<type_input, {
left: type_output_left;
right: type_output_right;
}>;
/**
* @author fenris
* @desc repeatedly applied serial composition
*/
function deferral_chain<type_value>(members: Array<type_deferral<type_value, type_value>>): type_deferral<type_value, type_value>;
/**
* @author fenris
*/
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
class class_deferral<type_input, type_output> {
/**
* @author fenris
*/
private subject;
/**
* @author fenris
*/
private constructor();
/**
* @author fenris
*/
private static _cram;
/**
* @author fenris
*/
private static _tear;
/**
* @author fenris
*/
static make<type_input, type_output>(handler: (input: type_input, convey: (value: type_output) => void) => void): class_deferral<type_input, type_output>;
/**
* @author fenris
*/
use(input: type_input, procedure: (value: type_output) => void): void;
/**
* @author fenris
*/
compose_serial<type_output_>(second: class_deferral<type_output, type_output_>): class_deferral<type_input, type_output_>;
/**
* @author fenris
*/
static chain<type_value>(members: Array<class_deferral<type_value, type_value>>): class_deferral<type_value, type_value>;
/**
* @author fenris
*/
static wrap<type_input, type_output>(function_: (input: type_input) => type_output): class_deferral<type_input, type_output>;
/**
* @author fenris
*/
static const_<type_value>(value: type_value): class_deferral<type_value, type_value>;
/**
* @author fenris
*/
static delay<type_output>(output: type_output, delay: int): class_deferral<any, type_output>;
}
}
declare namespace lib_plankton.call {
/**
* @author fenris
*/
function timeout(function_: () => void, delay: int): int;
/**
* @desc a definition for a value being "defined"
* @author neuc
*/
function is_def<type_value>(obj: type_value, null_is_valid?: boolean): boolean;
/**
* @desc returns the value if set and, when a type is specified, if the type is correct, if not return default_value
* @author neuc
*/
function def_val(value: any, default_value: any, type?: string, null_is_valid?: boolean): any;
/**
* @desc just the empty function; useful for some callbacks etc.
* @author fenris
*/
function nothing(): void;
/**
* @desc outputs
* @author fenris
*/
/**
* @desc converts the "arguments"-map into an array
* @param {Object} args
* @author fenris
*/
function args2list(args: any): Array<any>;
/**
* @desc provides the call for an attribute of a class as a regular function
* @param {string} name the name of the attribute
* @return {*}
* @author fenris
*/
function attribute<type_object, type_attribute>(name: string): (object: type_object) => type_attribute;
/**
* @desc provides a method of a class as a regular function
* @param {string} name the name of the method
* @return {function}
* @author fenris
*/
function method<type_object, type_output>(name: string): (object: type_object) => type_output;
/**
* @author fenris
*/
type type_unival = {
kind: string;
data?: any;
};
/**
* @author fenris
*/
function distinguish(unival: type_unival, handlers: {
[kind: string]: (data?: any) => any;
}, fallback?: (unival?: type_unival) => any): any;
/**
* Promise version of "setTimeout"
*
* @author fenris
*/
function defer<type_result>(seconds: int, action: (() => type_result)): Promise<type_result>;
/**
* for rate_limit_check
*
* @author fenris
*/
type type_mana_snapshot = {
timestamp: float;
value: float;
};
/**
* rate limiting algorithm, based on the idea of mana (magic power) in video games:
* - an actor has a fixed mana capacity, i.e. the maximum amount of available power
* - an actor has a fixed rate of mana regeneration, i.e. how fast the power is filled up (linear growth)
* - an action has a defined mana heft, i.e. how much power is required and deducted in order to execute it
* - mana states are represented by snapshots, i.e. the amount of power at a certain point in time
*
* @author fenris
*/
function rate_limit_check(setup: {
capacity: float;
regeneration_rate: float;
get_snapshot: (() => Promise<(null | type_mana_snapshot)>);
set_snapshot: ((snapshot: type_mana_snapshot) => Promise<void>);
update_snapshot: ((timestamp: float, value_increment: float) => Promise<void>);
}, heft: float): Promise<{
granted: boolean;
seconds: (null | float);
}>;
}
declare namespace lib_plankton.translate { declare namespace lib_plankton.translate {
/** /**
* @author fenris * @author fenris

File diff suppressed because it is too large Load diff

View file

@ -1,9 +1,9 @@
namespace _heimdall.checks namespace _heimdall.check_kinds
{ {
/** /**
*/ */
export type type_check = { export type type_check_kind = {
parameters_schema : (() => _heimdall.helpers.json_schema.type_schema); parameters_schema : (() => _heimdall.helpers.json_schema.type_schema);
normalize_order_node : ((node : any) => any); normalize_order_node : ((node : any) => any);
run : (parameters) => Promise<{condition : _heimdall.enum_condition; info : any;}>; run : (parameters) => Promise<{condition : _heimdall.enum_condition; info : any;}>;

View file

@ -38,7 +38,9 @@ namespace _heimdall.helpers.json_schema
description ?: string; description ?: string;
default ?: any; default ?: any;
minimum ?: int; minimum ?: int;
exclusiveMinimum ?: int;
maximum ?: int; maximum ?: int;
exclusiveMaximum ?: int;
enum ?: Array<any>; enum ?: Array<any>;
items ?: type_schema; items ?: type_schema;
anyOf ?: Array<type_schema>; anyOf ?: Array<type_schema>;

View file

@ -0,0 +1,25 @@
namespace _heimdall.helpers.sqlite
{
/**
*/
export function query_put(
database_path : string,
query_template : string,
query_arguments : Record<string, any>
) : Promise<any>
{
}
/**
*/
export function query_set(
database_path : string,
query_template : string,
query_arguments : Record<string, any>
) : Promise<any>
{
}
}

View file

@ -209,16 +209,16 @@ async function main(
process.stdout.write(version + "\n"); process.stdout.write(version + "\n");
} }
else { else {
const check_kind_implementations : Record<string, _heimdall.checks.type_check> = { const check_kind_implementations : Record<string, _heimdall.check_kinds.type_check_kind> = {
}; };
const channel_kind_implementations : Record<string, _heimdall.channels.type_channel> = { const notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind> = {
}; };
if (args.show_schema) { if (args.show_schema) {
process.stdout.write( process.stdout.write(
lib_plankton.json.encode( lib_plankton.json.encode(
_heimdall.order.schema_root( _heimdall.order.schema_root(
check_kind_implementations, check_kind_implementations,
channel_kind_implementations notification_kind_implementations
), ),
true true
) )
@ -227,7 +227,96 @@ async function main(
) )
} }
else { else {
process.stdout.write(JSON.stringify(args, undefined, "\t") + "\n"); const nm_path = require("path");
const nm_fs = require("fs");
if (! nm_fs.existsSync(args["order_path"])) {
process.stderr.write(
lib_plankton.translate.get(
"misc.order_file_not_found",
{
"path": args["order_path"],
}
)
);
}
else {
// get order data
const order = await _heimdall.order.load(
check_kind_implementations,
notification_kind_implementations,
nm_path.normalize(args["order_path"])
);
if (args["expose_full_order"]) {
process.stdout.write(lib_plankton.json.encode(order, true) + "\n");
}
else {
const database_path : string = (
(args["database_path"] !== null)
? args["database_path"]
: nm_path.join(
// TODO get path from fs or path module?
"/tmp",
lib_plankton.string.coin(
"monitoring-state-{{id}}.sqlite",
{
"id": lib_plankton.call.convey(
args["order_path"],
[
nm_path.normalize,
// encode(ascii),
x => lib_plankton.sha256.get(x),
x => x.slice(0, 8),
]
),
}
)
)
);
lib_plankton.log.info(
lib_plankton.translate.get("misc.state_file_path"),
{
"database_path": database_path,
}
);
// mutex check
if (nm_path.exists(args["mutex_path"])) {
lib_plankton.log.error(
lib_plankton.translate.get("misc.still_running"),
{
"mutex_path": args["mutex_path"],
}
);
process.exit(2);
}
else {
await _heimdall.state_repository.setup(database_path);
const clean_count : int = await _heimdall.state_repository.clean(
database_path,
args["time_to_live"],
args["erase_state"]
);
// create mutex file
await lib_plankton.file.write(args["mutex_path"], "");
order.checks.forEach(
check => {
if (! check.active) {
// do nothing
}
else {
process.stdout.write(JSON.stringify(order, undefined, "\t") + "\n");
}
}
);
// drop mutex file
await lib_plankton.file.delete(args["mutex_path"]);
}
}
}
} }
} }
} }

View file

@ -1,9 +1,9 @@
namespace _heimdall.channels namespace _heimdall.notification_kinds
{ {
/** /**
*/ */
export type type_channel = { export type type_notification_kind = {
parameters_schema : (() => _heimdall.helpers.json_schema.type_schema); parameters_schema : (() => _heimdall.helpers.json_schema.type_schema);
normalize_order_node : ((node : any) => any); normalize_order_node : ((node : any) => any);
notify : (parameters, name, data, state, info) => Promise<void>; notify : (parameters, name, data, state, info) => Promise<void>;

View file

@ -1,6 +1,55 @@
namespace _heimdall.order namespace _heimdall.order
{ {
/**
* @todo
*/
type type_schedule = any;
/**
*/
export type type_notification = {
kind : string;
parameters : any;
};
/**
*/
export type type_check_common = {
active ?: boolean;
threshold ?: int;
annoy ?: boolean;
schedule ?: type_schedule;
notifications ?: Array<type_notification>;
};
/**
*/
export type type_check = (
type_check_common
&
{
name : string;
title : string;
kind : string;
parameters : any;
custom : any;
}
);
/**
*/
export type type_order = {
defaults : type_check_common;
includes : Array<string>;
checks : Array<type_check>;
};
function schema_active( function schema_active(
) : _heimdall.helpers.json_schema.type_schema ) : _heimdall.helpers.json_schema.type_schema
{ {
@ -81,14 +130,14 @@ namespace _heimdall.order
function schema_notifications( function schema_notifications(
channel_implementations : Record<string, _heimdall.channels.type_channel> notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>
) )
{ {
return { return {
"type": "array", "type": "array",
"items": { "items": {
"anyOf": ( "anyOf": (
Object.entries(channel_implementations) Object.entries(notification_kind_implementations)
.map( .map(
([key, value]) => ({ ([key, value]) => ({
"title": ("notification channel '" + key + "'"), "title": ("notification channel '" + key + "'"),
@ -121,8 +170,8 @@ namespace _heimdall.order
export function schema_root( export function schema_root(
check_kind_implementations : Record<string, _heimdall.checks.type_check>, check_kind_implementations : Record<string, _heimdall.check_kinds.type_check_kind>,
channel_implementations : Record<string, _heimdall.channels.type_channel>, notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>,
) )
{ {
return { return {
@ -138,7 +187,7 @@ namespace _heimdall.order
"threshold": schema_threshold(), "threshold": schema_threshold(),
"annoy": schema_annoy(), "annoy": schema_annoy(),
"schedule": schema_schedule(), "schedule": schema_schedule(),
"notifications": schema_notifications(channel_implementations), "notifications": schema_notifications(notification_kind_implementations),
}, },
"required": [ "required": [
], ],
@ -170,7 +219,7 @@ namespace _heimdall.order
"threshold": schema_threshold(), "threshold": schema_threshold(),
"annoy": schema_annoy(), "annoy": schema_annoy(),
"schedule": schema_schedule(), "schedule": schema_schedule(),
"notifications": schema_notifications(channel_implementations), "notifications": schema_notifications(notification_kind_implementations),
}, },
"required": [ "required": [
"name", "name",
@ -266,24 +315,24 @@ namespace _heimdall.order
function normalize_notification( function normalize_notification(
channel_implementations : Record<string, _heimdall.channels.type_channel>, notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>,
node node
) )
{ {
if (! (node["kind"] in channel_implementations)) { if (! (node["kind"] in notification_kind_implementations)) {
throw new Error("invalid notification kind: " + node["kind"]); throw new Error("invalid notification kind: " + node["kind"]);
} }
else { else {
return { return {
"kind": node["kind"], "kind": node["kind"],
"parameters": channel_implementations[node["kind"]].normalize_order_node(node["parameters"]), "parameters": notification_kind_implementations[node["kind"]].normalize_order_node(node["parameters"]),
}; };
} }
} }
function normalize_defaults( function normalize_defaults(
channel_implementations : Record<string, _heimdall.channels.type_channel>, notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>,
node node
) )
{ {
@ -309,18 +358,23 @@ namespace _heimdall.order
"schedule": node_["schedule"], "schedule": node_["schedule"],
"notifications": ( "notifications": (
node_["notifications"] node_["notifications"]
.map(x => normalize_notification(channel_implementations, x)) .map(x => normalize_notification(notification_kind_implementations, x))
), ),
}; };
} }
/**
*/
function normalize_check( function normalize_check(
check_kind_implementations : Record<string, _heimdall.checks.type_check>, check_kind_implementations : Record<string, _heimdall.check_kinds.type_check_kind>,
channel_implementations : Record<string, _heimdall.channels.type_channel>, notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>,
defaults, defaults : type_check_common,
node node : {
) name : string;
kind : string;
}
) : type_check
{ {
if (! ("name" in node)) { if (! ("name" in node)) {
throw new Error("missing mandatory field in 'check' node: 'name'"); throw new Error("missing mandatory field in 'check' node: 'name'");
@ -330,70 +384,68 @@ namespace _heimdall.order
throw new Error("missing mandatory field in 'check' node: 'kind'"); throw new Error("missing mandatory field in 'check' node: 'kind'");
} }
else { else {
if (! (node["kind"] in check_kind_implementations)) { if (! (node.kind in check_kind_implementations)) {
throw new Error("invalid check kind: " + node["kind"]); throw new Error("invalid check kind: " + node.kind);
} }
else { else {
const node_ = Object.assign( const node_ : type_check = Object.assign(
Object.assign( Object.assign(
defaults, defaults,
{ {
"title": node["name"], "title": node.name,
"parameters": {}, "parameters": {},
"custom": null, "custom": null,
}, },
), ),
node node
); );
let node__ = {}; let check : type_check = {
if (true) { "name": node_.name,
node__["name"] = node_["name"]; "title": node_.title,
} "kind": node_.kind,
if (true) { "parameters": check_kind_implementations[node_.kind].normalize_order_node(node_.parameters),
node__["title"] = node_["title"]; "custom": node_.custom,
} };
if ("active" in node_) { if ("active" in node_) {
node__["active"] = node_["active"]; check.active = node_["active"];
} }
if ("threshold" in node_) { if ("threshold" in node_) {
node__["threshold"] = node_["threshold"]; check.threshold = node_["threshold"];
} }
if ("annoy" in node_) { if ("annoy" in node_) {
node__["annoy"] = node_["annoy"]; check.annoy = node_["annoy"];
} }
if ("schedule" in node_) { if ("schedule" in node_) {
node__["schedule"] = normalize_schedule(node_["schedule"]); check.schedule = normalize_schedule(node_["schedule"]);
} }
if ("notifications" in node_) { if ("notifications" in node_) {
node__["notifications"] = ( check.notifications = (
node_["notifications"] node_["notifications"]
.map( .map(
x => normalize_notification(channel_implementations, x), x => normalize_notification(notification_kind_implementations, x),
) )
); );
} }
if ("kind" in node_) {
node__["kind"] = node_["kind"];
}
if (true) {
node__["parameters"] = check_kind_implementations[node_["kind"]].normalize_order_node(node_["parameters"]);
}
if ("custom" in node_) { if ("custom" in node_) {
node__["custom"] = node_["custom"]; check.custom = node_["custom"];
} }
return node__; return check;
} }
} }
} }
} }
/**
*/
function normalize_root( function normalize_root(
check_kind_implementations : Record<string, _heimdall.checks.type_check>, check_kind_implementations : Record<string, _heimdall.check_kinds.type_check_kind>,
channel_implementations : Record<string, _heimdall.channels.type_channel>, notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>,
node, node,
options = {} options : {
) use_implicit_default_values ?: boolean;
} = {}
) : type_order
{ {
options = Object.assign( options = Object.assign(
{ {
@ -401,8 +453,8 @@ namespace _heimdall.order
}, },
options options
) )
let counts = {}; let counts : Record<string, int> = {};
let checks_raw = ( const checks_raw : Array<any> = (
("checks" in node) ("checks" in node)
? node["checks"] ? node["checks"]
: [] : []
@ -415,7 +467,7 @@ namespace _heimdall.order
counts[node_["name"]] += 1; counts[node_["name"]] += 1;
} }
); );
let fails : Array<[string, int]> = ( const fails : Array<[string, int]> = (
Object.entries(counts) Object.entries(counts)
.filter( .filter(
([key, value]) => (value > 1) ([key, value]) => (value > 1)
@ -432,20 +484,20 @@ namespace _heimdall.order
); );
} }
else { else {
let defaults_raw = ( const defaults_raw : any = (
("defaults" in node) ("defaults" in node)
? node["defaults"] ? node["defaults"]
: {} : {}
) )
let defaults = ( const defaults : type_check_common = (
options["use_implicit_default_values"] options.use_implicit_default_values
? normalize_defaults( ? normalize_defaults(
channel_implementations, notification_kind_implementations,
defaults_raw defaults_raw
) )
: defaults_raw : defaults_raw
) )
let includes = ( const includes : Array<string> = (
("includes" in node) ("includes" in node)
? node["includes"] ? node["includes"]
: [] : []
@ -458,7 +510,7 @@ namespace _heimdall.order
.map( .map(
node_ => normalize_check( node_ => normalize_check(
check_kind_implementations, check_kind_implementations,
channel_implementations, notification_kind_implementations,
defaults, defaults,
node_ node_
) )
@ -470,16 +522,21 @@ namespace _heimdall.order
export async function load( export async function load(
check_kind_implementations : Record<string, _heimdall.checks.type_check>, check_kind_implementations : Record<string, _heimdall.check_kinds.type_check_kind>,
channel_implementations : Record<string, _heimdall.channels.type_channel>, notification_kind_implementations : Record<string, _heimdall.notification_kinds.type_notification_kind>,
path : string, path : string,
options = {} options : {
) root ?: boolean;
already_included ?: Array<string>;
} = {}
) : Promise<type_order>
{ {
const nm_path = require("path");
options = Object.assign( options = Object.assign(
{ {
"root": true, "root": true,
"already_included": new Set([]), "already_included": [],
}, },
options options
) )
@ -497,16 +554,16 @@ namespace _heimdall.order
let path_ = includes[index]; let path_ = includes[index];
let sub_order = load( let sub_order = load(
check_kind_implementations, check_kind_implementations,
channel_implementations, notification_kind_implementations,
( (
_os.path.isabs(path_) nm_path.isAbsolute(path_)
? path_ ? path_
: _os.path.join(_os.path.dirname(path), path_) : nm_path.join(nm_path.dirname(path), path_)
), ),
{ {
"root": false, "root": false,
// TODO set union // TODO set union
"already_included": (options["already_included"] | {path}) "already_included": options.already_included.concat([path]),
} }
) )
if (! ("checks" in order_raw)) { if (! ("checks" in order_raw)) {
@ -521,7 +578,7 @@ namespace _heimdall.order
"name": lib_plankton.string.coin( "name": lib_plankton.string.coin(
"{{prefix}}.{{original_name}}", "{{prefix}}.{{original_name}}",
{ {
"prefix": _os.path.basename(path_).split(".")[0], "prefix": nm_path.basename(path_).split(".")[0],
"original_name": check["name"], "original_name": check["name"],
} }
), ),
@ -534,7 +591,7 @@ namespace _heimdall.order
} }
return normalize_root( return normalize_root(
check_kind_implementations, check_kind_implementations,
channel_implementations, notification_kind_implementations,
order_raw, order_raw,
{ {
"use_implicit_default_values": options["root"], "use_implicit_default_values": options["root"],

View file

@ -0,0 +1,37 @@
namespace _heimdall.state_repository
{
/**
*/
export async function setup(
database_path : string,
) : Promise<void>
{
const result = await _heimdall.helpers.sqlite.query_set(
database_path,
"CREATE TABLE IF NOT EXISTS results(check_name TEXT NOT NULL, timestamp INTEGER NOT NULL, condition TEXT NOT NULL, notification_sent BOOLEAN NOT NULL, info TEXT NOT NULL);",
{}
);
}
/**
*/
export async function clean(
database_path : string,
time_to_live : int,
erase_state : boolean,
) : Promise<int>
{
const result = await _heimdall.helpers.sqlite.query_put(
database_path,
"DELETE FROM results WHERE ((timestamp < :timestamp_min) OR :erase_state);",
{
"timestamp_min": ((Date.now() / 1000) - time_to_live),
"erase_state": erase_state,
}
);
return result.rowcount;
}
}

View file

@ -21,8 +21,10 @@
"lib/plankton/plankton.d.ts", "lib/plankton/plankton.d.ts",
"source/logic/condition.ts", "source/logic/condition.ts",
"source/logic/helpers/json_schema.ts", "source/logic/helpers/json_schema.ts",
"source/logic/checks/_type.ts", "source/logic/helpers/sqlite.ts",
"source/logic/channels/_type.ts", "source/logic/check_kinds/_abstract.ts",
"source/logic/notification_kinds/_abstract.ts",
"source/logic/state_repository.ts",
"source/logic/order.ts", "source/logic/order.ts",
"source/logic/main.ts" "source/logic/main.ts"
], ],

View file

@ -9,6 +9,8 @@ dir_plankton=${dir_lib}/plankton
## vars ## vars
modules="" modules=""
modules="${modules} call"
modules="${modules} sha256"
modules="${modules} string" modules="${modules} string"
modules="${modules} json" modules="${modules} json"
modules="${modules} file" modules="${modules} file"