@yuneta/gobj-js 7.7.3 → 7.8.0

package/README.md

@@ -477,6 +477,16 @@ gobj_list_persistent_attrs(gobj, keys)
 
 Attributes marked `SDF_PERSIST` are automatically saved/loaded.
 
+**Always name what you save**: `gobj_save_persistent_attrs(gobj, "attr_name")`
+(a string, or a list/dict of names). The bare call saves every `SDF_PERSIST`
+attr, which is wasteful and can clobber attrs the caller never touched.
+
+**Check the result.** `db_save_persistent_attrs()` / `gobj_save_persistent_attrs()`
+return **`0` on success, `-1` on failure**, and a failure is logged through
+`log_error`. `localStorage` can *refuse* a write (quota exceeded, private mode,
+storage blocked): treating that as saved leaves the in-memory attr and the UI
+showing a value the store rejected, which the next reload silently loses.
+
 ### Helpers & Utilities
 
 ```javascript
@@ -572,10 +582,54 @@ trace_msg(format, ...args)       // cyan, prefixed "MSG"
 trace_json(json, msg)            // dir-dump a JSON object
 
 // Redirect error/warning output to a single remote handler
-// (info/debug always go to the browser console)
 set_remote_log_functions(remote_log_fn)   // fn(message) — single function
+
+// Receive every log record (any level) in your own sink
+set_log_callback(fn)                      // fn(level, message)
+
+// Gate the DIRECT browser-console writes of all the functions above
+set_console_log_enabled(enabled)          // default: true (unchanged behaviour)
 ```
 
+**Three independent output paths.** `set_console_log_enabled(false)` silences
+only the `console.*` writes: the log-sink callback (`set_log_callback`) and the
+remote log functions (`set_remote_log_functions`) still fire. That is what lets
+a GUI route framework output — **including the automata/FSM trace, which arrives
+as `debug`** — into its own monitor window while keeping the browser console
+clean (gobj-ui's dev-window "Output" selector does exactly this).
+
+### i18n: `refresh_language` and the `data-i18n-*` family
+
+The runtime does not translate anything itself — the **app** owns the
+translator (i18next, typically) and passes it in as `t`. What the runtime
+provides is the mechanism to **re-translate live DOM** when the language
+changes:
+
+```javascript
+refresh_language(element, t)     // element defaults to `document`
+```
+
+It only re-translates a node that **carries its key**, so passing a string
+through `t()` once at build time is not enough — that text is frozen in the
+mount-time language for the life of the view. Tag the DOM instead:
+
+| Attribute | Re-translates |
+|---|---|
+| `data-i18n` | the element's first text node |
+| `data-i18n-title` | the `title` attribute (hover tooltip) |
+| `data-i18n-aria-label` | the `aria-label` (assistive-tech name) |
+| `data-i18n-placeholder` | the `placeholder` of an input/textarea |
+
+The three attribute variants exist because `data-i18n` walks **text nodes**,
+which cannot reach an attribute. Anything a third-party **widget** draws is
+reachable by none of them — re-render it from the language-change handler
+instead.
+
+**A missing key is invisible**: i18next answers an unknown key with the key
+itself, so it renders as lower-case English and never changes language. Do not
+compose data into a key either (`` `${key} · ${t(mode)}` ``) — split it so each
+translatable half carries its own key.
+
 ### String Formatting
 
 ```javascript
@@ -600,6 +654,10 @@ register_c_yuno();
 
 Key attributes: `yuno_name`, `yuno_role`, `yuno_id`, `yuno_version`, `yuno_release`, `yuneta_version`, `required_services`, `tracing`, `start_date`, `node_uuid`, `__username__`
 
+The yuno's `required_services` is the **fallback** for links that declare none
+of their own. A multi-link yuno should set the list on each `C_IEVENT_CLI`
+instead — see [C_IEVENT_CLI](#c_ievent_cli) below.
+
 ### C_TIMER
 
 Manages timeouts and periodic timers.
@@ -638,7 +696,23 @@ let remote = gobj_create_service("backend", "C_IEVENT_CLI", {
 }, gobj_yuno());
 ```
 
-Key attributes: `url`, `jwt`, `wanted_yuno_role`, `wanted_yuno_name`, `wanted_yuno_service`, `remote_yuno_role`, `remote_yuno_name`, `remote_yuno_service`
+Key attributes: `url`, `jwt`, `wanted_yuno_role`, `wanted_yuno_name`, `wanted_yuno_service`, `remote_yuno_role`, `remote_yuno_name`, `remote_yuno_service`, `required_services`, `timeout_retry`, `timeout_retry_max`
+
+**`required_services`** (default `[]`) is the list this link advertises in its
+identity_card, which the remote's `C_AUTHZ` uses to authorize commands. It is
+**per link**: empty falls back to the yuno's own `required_services`, so a
+single-link yuno needs nothing. A **multi-link** yuno must set it per link — a
+yuno-wide list can only be the union of every backend's services, so each
+backend would be handed the service names of all the others, and get a card
+naming services it does not host.
+
+**Reconnect backoff.** A dropped link retries after `timeout_retry` (5s), then
+**doubles** up to `timeout_retry_max` (60s), with ±20% jitter. The jitter is
+what breaks lockstep, so N links that dropped together do not stampede a backend
+that is just coming back. The backoff resets when a session is actually reached,
+and on `mt_start` — a deliberate reconnect never inherits a previous run's
+penalty. For the old fixed-interval behaviour set `timeout_retry_max` equal to
+`timeout_retry`.
 
 ---
 

package/dist/gobj-js.cjs.js

@@ -2630,6 +2630,10 @@ var __log_callback__ = null;
 function set_log_callback(fn) {
 	__log_callback__ = typeof fn === "function" ? fn : null;
 }
+var __console_output_enabled__ = true;
+function set_console_log_enabled(enabled) {
+	__console_output_enabled__ = enabled ? true : false;
+}
 var __in_log_callback__ = false;
 function emit_log_callback(level, msg, hora) {
 	if (__log_callback__ && !__in_log_callback__) {
@@ -2675,9 +2679,10 @@ function format_log(format) {
 function log_error(format) {
 	let msg = format_log(format);
 	let hora = current_timestamp();
-	if (f_error) if (f_error === window.console.error) f_error("%c" + hora + " ERROR: " + String(msg), "color:red");
-	else {
-		window.console.error("%c" + hora + " ERROR: " + String(msg), "color:red");
+	if (f_error) if (f_error === window.console.error) {
+		if (__console_output_enabled__) f_error("%c" + hora + " ERROR: " + String(msg), "color:red");
+	} else {
+		if (__console_output_enabled__) window.console.error("%c" + hora + " ERROR: " + String(msg), "color:red");
 		f_error(`${hora} ERROR: ${String(msg)}`);
 	}
 	emit_log_callback("error", msg, hora);
@@ -2685,9 +2690,10 @@ function log_error(format) {
 function log_warning(format) {
 	let msg = format_log(format);
 	let hora = current_timestamp();
-	if (f_warning) if (f_warning === window.console.warn) f_warning("%c" + hora + " WARNING: " + String(msg), "color:yellow");
-	else {
-		window.console.warn("%c" + hora + " WARNING: " + String(msg), "color:yellow");
+	if (f_warning) if (f_warning === window.console.warn) {
+		if (__console_output_enabled__) f_warning("%c" + hora + " WARNING: " + String(msg), "color:yellow");
+	} else {
+		if (__console_output_enabled__) window.console.warn("%c" + hora + " WARNING: " + String(msg), "color:yellow");
 		f_warning(`${hora} WARNING: ${String(msg)}`);
 	}
 	emit_log_callback("warning", msg, hora);
@@ -2695,24 +2701,32 @@ function log_warning(format) {
 function log_info(format) {
 	let msg = format_log(format);
 	let hora = current_timestamp();
-	if (f_info) f_info("%c" + hora + " INFO: " + String(msg), "color:cyan");
+	if (f_info) {
+		if (__console_output_enabled__) f_info("%c" + hora + " INFO: " + String(msg), "color:cyan");
+	}
 	emit_log_callback("info", msg, hora);
 }
 function log_debug(format) {
 	let msg = format_log(format);
 	let hora = current_timestamp();
-	if (f_debug) f_debug("%c" + hora + " DEBUG: " + String(msg), "color:silver");
+	if (f_debug) {
+		if (__console_output_enabled__) f_debug("%c" + hora + " DEBUG: " + String(msg), "color:silver");
+	}
 	emit_log_callback("debug", msg, hora);
 }
 function trace_msg(format) {
 	let msg = format_log(format);
 	let hora = current_timestamp();
-	if (f_debug) f_debug("%c" + hora + " MSG: " + String(msg), "color:cyan");
+	if (f_debug) {
+		if (__console_output_enabled__) f_debug("%c" + hora + " MSG: " + String(msg), "color:cyan");
+	}
 	emit_log_callback("msg", msg, hora);
 }
 function trace_json(jn, msg) {
-	if (msg) window.console.warn("=====> " + msg);
-	window.console.dir(jn);
+	if (__console_output_enabled__) {
+		if (msg) window.console.warn("=====> " + msg);
+		window.console.dir(jn);
+	}
 	emit_log_callback("json", jn, current_timestamp());
 }
 /************************************************************
@@ -3525,17 +3539,26 @@ function kw_get_local_storage_value(key, default_value, create = false) {
 }
 /********************************************
 *  Save a local attribute
+*
+*  Returns 0 on success, -1 when the value did NOT reach the store.
+*  It used to return nothing and only console.warn, so every caller up the
+*  chain (db_save_persistent_attrs -> gobj_save_persistent_attrs -> the app)
+*  reported success on a store that had rejected the write: a full or blocked
+*  localStorage (quota, private mode) silently discarded the change while the
+*  UI showed it as saved.
 ********************************************/
 function kw_set_local_storage_value(key, value) {
-	if (typeof window === "undefined" || !window.localStorage) return;
+	if (typeof window === "undefined" || !window.localStorage) return 0;
 	if (!key || value === void 0) {
-		window.console.warn(`Invalid key or value for localStorage: key=${key}, value=${value}`);
-		return;
+		log_error(`kw_set_local_storage_value(): invalid key or value: key=${key}`);
+		return -1;
 	}
 	try {
 		window.localStorage.setItem(key, JSON.stringify(value));
+		return 0;
 	} catch (e) {
-		window.console.warn(`Error saving localStorage key "${key}":`, e);
+		log_error(`kw_set_local_storage_value(): cannot save "${key}" (storage full or blocked?): ${e && e.message ? e.message : e}`);
+		return -1;
 	}
 }
 /********************************************
@@ -4510,6 +4533,10 @@ function refresh_language(element, t) {
 		let value = elem.getAttribute("data-i18n-aria-label");
 		if (value) elem.setAttribute("aria-label", t(value));
 	});
+	element.querySelectorAll("[data-i18n-placeholder]").forEach(function(elem) {
+		let value = elem.getAttribute("data-i18n-placeholder");
+		if (value) elem.setAttribute("placeholder", t(value));
+	});
 }
 /************************************************************
 * Example Usage
@@ -4691,13 +4718,16 @@ function db_load_persistent_attrs(gobj, keys) {
 	}
 }
 /************************************************************
-*
+*  Returns 0 on success, -1 when the attrs did NOT reach the store
+*  (quota exceeded, private mode, storage disabled). Callers must check
+*  it: a discarded write with a UI that shows the value as saved is the
+*  worst of both worlds.
 ************************************************************/
 function db_save_persistent_attrs(gobj, keys) {
 	let attrs = kw_clone_by_keys(gobj, gobj_read_attrs(gobj, sdata_flag_t.SDF_PERSIST, 0), keys, false);
 	let jn_file = kw_get_local_storage_value(_get_persistent_path(gobj), null, false);
 	if (jn_file && is_object(jn_file)) json_object_update_missing(attrs, jn_file);
-	kw_set_local_storage_value(_get_persistent_path(gobj), attrs);
+	return kw_set_local_storage_value(_get_persistent_path(gobj), attrs);
 }
 /************************************************************
 *
@@ -5446,7 +5476,9 @@ var attrs_table = [
 	SDATA(data_type_t.DTP_STRING, "jwt", sdata_flag_t.SDF_PERSIST, "", "JWT"),
 	SDATA(data_type_t.DTP_STRING, "cert_pem", sdata_flag_t.SDF_PERSIST, "", "SSL server certification, PEM str format"),
 	SDATA(data_type_t.DTP_JSON, "extra_info", sdata_flag_t.SDF_RD, "{}", "dict data set by user, added to the identity card msg."),
-	SDATA(data_type_t.DTP_INTEGER, "timeout_retry", sdata_flag_t.SDF_RD, "5000", "timeout waiting idAck"),
+	SDATA(data_type_t.DTP_LIST, "required_services", sdata_flag_t.SDF_RD, "[]", "Services this LINK requires (identity card). Empty = the yuno's `required_services`, as before. A yuno with several links to DIFFERENT backends must set it per link: the yuno-wide list is the union, so every backend is told the service names of all the others."),
+	SDATA(data_type_t.DTP_INTEGER, "timeout_retry", sdata_flag_t.SDF_RD, "5000", "First reconnect delay (ms). It BACKS OFF from here, doubling up to timeout_retry_max, and resets when a session is reached"),
+	SDATA(data_type_t.DTP_INTEGER, "timeout_retry_max", sdata_flag_t.SDF_RD, "60000", "Cap of the reconnect backoff (ms). Set it equal to timeout_retry for the old fixed-interval behaviour"),
 	SDATA(data_type_t.DTP_INTEGER, "timeout_idack", sdata_flag_t.SDF_RD, "5000", "timeout waiting idAck"),
 	SDATA(data_type_t.DTP_POINTER, "subscriber", 0, 0, "subscriber of output-events. If null then subscriber is the parent"),
 	SDATA_END()
@@ -5459,7 +5491,8 @@ var PRIVATE_DATA = {
 	gobj_timer: null,
 	inform_on_close: false,
 	websocket: null,
-	inside_on_open: false
+	inside_on_open: false,
+	retry_ms: 0
 };
 var __gclass__ = null;
 /******************************
@@ -5507,6 +5540,7 @@ function mt_writing(gobj, path) {
 function mt_start(gobj) {
 	let priv = gobj.priv;
 	gobj_start(priv.gobj_timer);
+	priv.retry_ms = 0;
 	priv.websocket = setup_websocket(gobj);
 	return 0;
 }
@@ -5765,6 +5799,8 @@ function send_identity_card(gobj) {
 	let yuno_version = gobj_read_str_attr(gobj_yuno(), "yuno_version");
 	let yuno_release = gobj_read_str_attr(gobj_yuno(), "yuno_release");
 	let yuno_tag = gobj_read_str_attr(gobj_yuno(), "yuno_tag");
+	let required_services = gobj_read_attr(gobj, "required_services");
+	if (!required_services || !required_services.length) required_services = gobj_read_attr(gobj_yuno(), "required_services");
 	let kw = {
 		"yuno_role": gobj_yuno_role(),
 		"yuno_id": gobj_yuno_id(),
@@ -5783,7 +5819,7 @@ function send_identity_card(gobj) {
 		"id": node_uuid(),
 		"user_agent": typeof window !== "undefined" ? window.navigator.userAgent : "",
 		"language": typeof window !== "undefined" ? window.navigator.language : "",
-		"required_services": gobj_read_attr(gobj_yuno(), "required_services")
+		"required_services": required_services
 	};
 	msg_iev_push_stack(gobj, kw, IEVENT_STACK_ID, build_cli_ievent_request(gobj, gobj_name(gobj_parent(gobj)), null));
 	msg_iev_set_msg_type(gobj, kw, "__identity__");
@@ -5912,9 +5948,37 @@ function ac_on_close(gobj, event, kw, src) {
 			was_clean: e.wasClean
 		});
 	}
-	if (gobj_is_running(gobj)) set_timeout(priv.gobj_timer, gobj_read_integer_attr(gobj, "timeout_retry"));
+	if (gobj_is_running(gobj)) set_timeout(priv.gobj_timer, next_retry(gobj));
 	return 0;
 }
+/***************************************************************
+*  How long to wait before the next reconnect attempt.
+*
+*  The delay used to be a constant (`timeout_retry`, 5s), for ever. A
+*  backend that is down — or a URL with a typo, which never comes back —
+*  was therefore hit every 5 seconds for the whole life of the tab, by
+*  EVERY link pointed at it, all in lockstep. It backs off now: from
+*  `timeout_retry`, doubling, capped at `timeout_retry_max`.
+*
+*  The jitter (±20%) is what breaks the lockstep. Without it, N links that
+*  went down together retry together for ever — a thundering herd against a
+*  backend that is just coming back up. It is the one place a random number
+*  earns its keep.
+*
+*  Reset to zero when a session is actually reached
+*  (ac_identity_card_ack), so a link that flaps once does not carry a
+*  minute-long penalty into its next real drop.
+***************************************************************/
+function next_retry(gobj) {
+	let priv = gobj.priv;
+	let base = gobj_read_integer_attr(gobj, "timeout_retry");
+	let max = gobj_read_integer_attr(gobj, "timeout_retry_max");
+	if (max < base) max = base;
+	priv.retry_ms = priv.retry_ms ? Math.min(priv.retry_ms * 2, max) : base;
+	let jitter = priv.retry_ms * .2;
+	let ms = priv.retry_ms - jitter + Math.random() * 2 * jitter;
+	return Math.max(1, Math.round(ms));
+}
 /********************************************
 *
 ********************************************/
@@ -5955,6 +6019,7 @@ function ac_identity_card_ack(gobj, event, kw, src) {
 	} else {
 		gobj_change_state(gobj, "ST_SESSION");
 		priv.inside_on_open = true;
+		priv.retry_ms = 0;
 		if (!priv.inform_on_close) {
 			priv.inform_on_close = true;
 			let kw_on_open = {
@@ -6378,6 +6443,7 @@ exports.register_c_yuno = register_c_yuno;
 exports.safeSrc = safeSrc;
 exports.sdata_flag_t = sdata_flag_t;
 exports.send_http_json_post = send_http_json_post;
+exports.set_console_log_enabled = set_console_log_enabled;
 exports.set_log_callback = set_log_callback;
 exports.set_remote_log_functions = set_remote_log_functions;
 exports.set_timeout = set_timeout;