tina4ruby 3.13.157 → 3.13.158

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a7657b8f005b569518dea4529a63b71242fd306d2a694a846f8857018f3c194
-  data.tar.gz: 8170d55c05ce85b8517235da0a01531951567eccb2f096c60b72640268325131
+  metadata.gz: 9821daa34797e73cbeb2363f1df52e61a22a17eb2b7e44412483c72a02176866
+  data.tar.gz: 4eb81de452060f402677cecb522bd11417c968c50940a39cfbf7f9cd42b5700a
 SHA512:
-  metadata.gz: 0277c5bd8117ca2e0ae68623026a15fc9c89e34e12d9aad1a56e02a675c924fb27c0adf64e516159d6dff1a9f5dba4f796ff6f65b36adea2659c317808955415
-  data.tar.gz: 11d29cbb61293443b30ed7effd36d13ec8e71c5d73aeabfd01d4cd0c05321fb683c5e59b75eaea5561719d81810ccdc84fbb74f268befa4f78302304cf2ccc29
+  metadata.gz: b3350a878be47194f468507e910d6975c347eb717d101aeb7d78c4cec836156ab3ee06c234ec63b1c7a84cb8b8e5fcc3d11f226d688813360f7102fe55a61abb
+  data.tar.gz: f065e3b6de1441f44bd6104f6b9eb2e46c5c5fb856043ec9e86abf7b6a738305130259cf6697239d54a9cd390a97ca77775466e0476c8272d863d672acafb15b

data/CHANGELOG.md

@@ -6,6 +6,30 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.158 - 2026-11-05
+
+### Added
+- Raw TCP service primitive (feature 142, ADR-0102): an in-process TCP listener with
+  on_connect/on_data/on_close callbacks and a connection registry for server->device push.
+- ORM chainable `skip()` / `offset()` / `take()` on the query builder.
+- CodeQL static security scanning in CI.
+
+### Changed
+- Kafka queue backend commits consumer-group offsets durably, per record, and consumes
+  externally-produced records (ADR-0105).
+- Frond `date` filter accepts both strftime and Twig/PHP `date()` letters (ADR-0103); an
+  unclosed `{% block %}` now fails loud (ADR-0104); `form.collect()` sends every selected
+  option of a `<select multiple>`.
+
+### Security
+- frond.js no longer sends the signed-in bearer token to another origin or accepts a
+  FreshToken from one, and no longer writes the token into a `formToken` field
+  (GHSA-q2gc-fpw5-3v3c).
+- The dev-reload WebSocket is gated on the raw socket peer, not only the Host header (GHSA-ppcq-wpj3-px7m).
+- Resolves additional advisories shipped in this release; full notes in the documentation.
+- A scheme-less `TINA4_DATABASE_URL` no longer logs its password (GHSA-cxqw-5cwf-wv3r).
+- The dev file-save endpoint follows a dangling symlink before the containment check (GHSA-3p39-mqxh-gjxf).
+
 ## 3.13.157 - 2026-11-02
 
 ### Added

data/lib/tina4/database.rb

@@ -530,7 +530,7 @@ module Tina4
       Tina4::Log.info("Database connected: #{@driver_name}")
       @connect_error = nil
     rescue => e
-      Tina4::Log.error("Database connection failed: #{e.message}")
+      Tina4::Log.error("Database connection failed: #{scrub_connection_string(e.message)}")
       @connected = false
       # REMEMBER the cause. Logging alone is not enough: the driver's own
       # connection stays nil, so the next call used to die inside the driver as
@@ -582,9 +582,21 @@ module Tina4
     def connect_error_message
       target = safe_connection_target
       "Database not connected (#{@driver_name}#{target.empty? ? '' : " -> #{target}"}): " \
-        "#{@connect_error.class}: #{@connect_error.message}"
+        "#{@connect_error.class}: #{scrub_connection_string(@connect_error.message)}"
     end
 
+    # The driver's message with the raw connection string taken out. libpq quotes
+    # a scheme-less value whole as the host it could not resolve -
+    #   could not translate host name "postgres//u:pass@h/app" to address
+    # - password included.
+    def scrub_connection_string(text)
+      raw = @connection_string.to_s
+      return text.to_s if raw.empty?
+
+      text.to_s.gsub(raw) { Tina4::DatabaseUrl.redact(raw) }
+    end
+    private :scrub_connection_string
+
     # The connection string with any password stripped, so a raised error can name
     # the target without leaking a credential into a log or an HTTP 500 body.
     #

data/lib/tina4/database_url.rb

@@ -180,9 +180,13 @@ module Tina4
     def self.scrub(text)
       head, separator, rest = text.to_s.partition("://")
 
-      # No "://" - a bare file path, or an ODBC/keyword string. There is no
-      # userinfo to find, so only the keyword form can hide a secret here.
-      return scrub_keywords(text.to_s) if separator.empty?
+      # No "://" - a bare file path, an ODBC/keyword string, or a URL that lost
+      # its ":" or a "/" (`postgres//u:pass@host/app`). An "@" means userinfo may
+      # be in front of it, so take the credential out the same way as below.
+      if separator.empty?
+        text = text.to_s
+        return scrub_keywords(text.include?("@") ? redact_authority(text) : text)
+      end
 
       # A head that is not a scheme is unknown text, and unknown text may BE the
       # secret (the measured Python case was `notaurl-with-SuperSecret123`).

data/lib/tina4/dev_admin.rb

@@ -1727,24 +1727,34 @@ module Tina4
         root = real_path_of(File.expand_path(Dir.pwd))
         resolved = real_path_of(File.expand_path(rel_path.to_s, root))
         roots = [root] + extra_roots.compact.map { |r| real_path_of(File.expand_path(r.to_s)) }
-        unless roots.any? { |r| resolved == r || resolved.start_with?(r.chomp("/") + "/") }
+        unless resolved && roots.any? { |r| r && (resolved == r || resolved.start_with?(r.chomp("/") + "/")) }
           raise ArgumentError, "path escapes project directory"
         end
         resolved
       end
 
       # Real path of +path+: the deepest existing ancestor is realpath'd and the
-      # not-yet-existing tail (a new file being saved) is appended.
-      def real_path_of(path)
+      # not-yet-existing tail (a new file being saved) is appended. A dangling
+      # symlink is followed to the place a write through it would land, the way
+      # McpDevTools.real_path_of does. nil when it cannot be resolved (a link
+      # loop, or an unreadable link), so the caller refuses it.
+      def real_path_of(path, hops = 0)
         existing = path
         tail = []
         until File.exist?(existing) || File.symlink?(existing) || existing == File.dirname(existing)
           tail.unshift(File.basename(existing))
           existing = File.dirname(existing)
         end
-        File.join(File.realpath(existing), *tail)
+        return File.join(File.realpath(existing), *tail) if File.exist?(existing)
+        return nil if hops >= 40
+
+        # A dangling symlink. Its target is joined as text, not normalised, so a
+        # ".." after a linked component is resolved the way the OS will follow it.
+        target = File.readlink(existing)
+        base = target.start_with?("/") ? target : File.join(File.dirname(existing), target)
+        real_path_of(File.join(base, *tail), hops + 1)
       rescue SystemCallError
-        path
+        nil
       end
 
       # Project-relative form of a resolved path, for the secret denylist.

data/lib/tina4/dispatch_pipeline.rb

@@ -199,6 +199,11 @@ module Tina4
       if ctx.path.start_with?("/__dev") && !Tina4::DevAdmin.dev_host_allowed?(ctx.env)
         return [403, { "content-type" => "text/plain" }, ["Forbidden: host not allowed"]]
       end
+      # ...and only from a raw socket peer the /__dev HTTP gate would let in, so
+      # a remote caller that claims "Host: localhost" cannot open it.
+      if ctx.path.start_with?("/__dev") && !Tina4::DevAdmin.dev_peer_allowed?((ctx.env["REMOTE_ADDR"] || "").to_s)
+        return [403, { "content-type" => "text/plain" }, ["Forbidden: peer not allowed"]]
+      end
 
       ws_result = Tina4::Router.find_ws_route(ctx.path)
       return nil unless ws_result

data/lib/tina4/frond.rb

@@ -28,6 +28,13 @@ module Tina4
   class SafeString < String
   end
 
+  # Raised when a Frond template is malformed and cannot be rendered safely
+  # (ADR-0104) -- an unclosed {% block %} or a cut-short {% endblock % whose
+  # closing %} is missing. Failing loud surfaces the real cause to a developer
+  # (or an AI agent) instead of a page served 200 with its body quietly dropped.
+  class FrondSyntaxError < StandardError
+  end
+
   class Frond
     # -- Class-level registries ------------------------------------------------
     # Persist globals, filters, and tests across hot-reloads and across module
@@ -569,6 +576,62 @@ module Tina4
       @allowed_tags.include?(tag)
     end
 
+    PHP_MONTHS = %w[January February March April May June July August September October November December].freeze
+    # cwday indexing: Monday == 1 .. Sunday == 7, so PHP_DAYS[cwday - 1].
+    PHP_DAYS = %w[Monday Tuesday Wednesday Thursday Friday Saturday Sunday].freeze
+
+    # Format a date/time with Twig/PHP date() letters (English names) — ADR-0103.
+    #
+    # Letters are mapped character by character; a backslash escapes the next
+    # character, and any unmapped character is emitted literally (PHP's rule).
+    # English month/day names are hardcoded so the output matches every other
+    # Tina4 framework regardless of the host locale.
+    def self.php_date(dt, fmt)
+      hour   = dt.respond_to?(:hour) ? dt.hour : 0
+      minute = dt.respond_to?(:min)  ? dt.min  : 0
+      second = dt.respond_to?(:sec)  ? dt.sec  : 0
+      h12 = hour % 12
+      h12 = 12 if h12.zero?
+      cwday = dt.cwday   # 1 == Monday .. 7 == Sunday
+      wday  = dt.wday    # 0 == Sunday .. 6 == Saturday
+      out = +""
+      i = 0
+      n = fmt.length
+      while i < n
+        c = fmt[i]
+        if c == "\\" && i + 1 < n
+          out << fmt[i + 1]
+          i += 2
+          next
+        end
+        out << case c
+               when "Y" then format("%04d", dt.year)
+               when "y" then format("%02d", dt.year % 100)
+               when "m" then format("%02d", dt.month)
+               when "n" then dt.month.to_s
+               when "d" then format("%02d", dt.day)
+               when "j" then dt.day.to_s
+               when "H" then format("%02d", hour)
+               when "G" then hour.to_s
+               when "h" then format("%02d", h12)
+               when "g" then h12.to_s
+               when "i" then format("%02d", minute)
+               when "s" then format("%02d", second)
+               when "A" then hour < 12 ? "AM" : "PM"
+               when "a" then hour < 12 ? "am" : "pm"
+               when "D" then PHP_DAYS[cwday - 1][0, 3]
+               when "l" then PHP_DAYS[cwday - 1]
+               when "M" then PHP_MONTHS[dt.month - 1][0, 3]
+               when "F" then PHP_MONTHS[dt.month - 1]
+               when "N" then cwday.to_s
+               when "w" then wday.to_s
+               else c
+               end
+        i += 1
+      end
+      out
+    end
+
     # Utility: HTML escape
     def self.escape_html(str)
       str.to_s.gsub(HTML_ESCAPE_RE, HTML_ESCAPE_MAP)
@@ -989,7 +1052,14 @@ module Tina4
           end
         end
 
-        pos = content_start unless matched # malformed -- skip forward
+        unless matched
+          # Unclosed {% block %} (or a cut-short {% endblock % whose %} is
+          # missing, so the close regex never matches) -- fail loud
+          # (tina4#286/#290) rather than silently dropping the body. Still
+          # bounded: we raise, we never loop (tina4#271).
+          raise FrondSyntaxError,
+                "{% block #{name} %} is never closed (missing or malformed {% endblock %})"
+        end
       end
 
       blocks
@@ -1061,12 +1131,10 @@ module Tina4
         end
 
         if close_match.nil?
-          # Malformed template (no matching endblock) -- keep the rest
-          # verbatim rather than lose it, the same leniency extract_blocks
-          # applies to this case.
-          pieces << source[m_open.begin(0)..]
-          pos = len
-          break
+          # Unclosed {% block %} -- fail loud (tina4#286/#290), matching
+          # extract_blocks, rather than silently keeping the rest verbatim.
+          raise FrondSyntaxError,
+                "{% block #{name} %} is never closed (missing or malformed {% endblock %})"
         end
 
         parent_content = source[content_start...close_match.begin(0)]
@@ -3195,12 +3263,14 @@ module Tina4
           begin
             if v.is_a?(String)
               dt = DateTime.parse(v)
-              dt.strftime(fmt)
             elsif v.respond_to?(:strftime)
-              v.strftime(fmt)
+              dt = v
             else
-              v.to_s
+              return v.to_s
             end
+            # A strftime-style format (any with %) stays strftime — back-compatible;
+            # any other format is Twig/PHP date() letters (ADR-0103).
+            fmt.include?("%") ? dt.strftime(fmt) : Frond.php_date(dt, fmt)
           rescue
             v.to_s
           end

data/lib/tina4/public/bundled-component-provenance.json

@@ -9,12 +9,12 @@
     {
       "path": "js/frond.min.js",
       "component": "tina4-css",
-      "sha256": "4cbaf2131492225d87205d8982c4af5035538e9812e704b43f217f4ac4a5dafc"
+      "sha256": "1c46dc669fe6ebed980bef6ecab197b73fc0697488aff5746ee4fe6e8a64d7cd"
     },
     {
       "path": "js/frond.js",
       "component": "tina4-css",
-      "sha256": "77560a0800034d91f8ccb5d726b69ff763881b96e39c5d0b6ee7186060c2d27a"
+      "sha256": "471cdcf1eae45142dce5a9755ce4d89e4e816989f3534ae2af56308ec4dcae65"
     },
     {
       "path": "js/tina4.min.js",

data/lib/tina4/public/js/frond.js

@@ -23,6 +23,13 @@ var _frondModule = (() => {
     frond: () => frond
   });
   var _token = null;
+  function _sameOrigin(url) {
+    try {
+      return new URL(url, window.location.href).origin === window.location.origin;
+    } catch {
+      return false;
+    }
+  }
   function request(url, options) {
     let opts;
     if (typeof options === "function") {
@@ -33,7 +40,8 @@ var _frondModule = (() => {
     const method = (opts.method || "GET").toUpperCase();
     const xhr = new XMLHttpRequest();
     xhr.open(method, url, true);
-    if (_token !== null) {
+    const sameOrigin = _sameOrigin(url);
+    if (_token !== null && sameOrigin) {
       xhr.setRequestHeader("Authorization", "Bearer " + _token);
     }
     if (opts.headers) {
@@ -57,7 +65,8 @@ var _frondModule = (() => {
     }
     xhr.onload = function() {
       const freshToken = xhr.getResponseHeader("FreshToken");
-      if (freshToken && freshToken !== "") {
+      const answeredBySameOrigin = sameOrigin && (!xhr.responseURL || _sameOrigin(xhr.responseURL));
+      if (freshToken && freshToken !== "" && answeredBySameOrigin) {
         _token = freshToken;
       }
       let content = xhr.response;
@@ -169,8 +178,12 @@ var _frondModule = (() => {
      * Collect all form field values into a FormData object.
      *
      * Handles inputs, selects, textareas, file uploads (including
-     * multi-file), checkboxes, and radio buttons. Updates formToken
-     * hidden fields automatically.
+     * multi-file), checkboxes, and radio buttons.
+     *
+     * A `formToken` field is sent as the server rendered it. frond never
+     * writes the bearer into it: the bearer travels in the Authorization
+     * header (own origin only), and the server accepts only a form token in
+     * the formToken slot.
      *
      * @param formId - DOM id of the form (without '#').
      * @returns Populated FormData instance.
@@ -180,9 +193,6 @@ var _frondModule = (() => {
       const elements = document.querySelectorAll("#" + formId + " select, #" + formId + " input, #" + formId + " textarea");
       for (let i = 0; i < elements.length; i++) {
         const el = elements[i];
-        if (el.name === "formToken" && _token !== null) {
-          el.value = _token;
-        }
         if (!el.name) continue;
         if (el.type === "file") {
           const files = el.files;
@@ -204,6 +214,15 @@ var _frondModule = (() => {
           } else if (el.type !== "radio") {
             fd.append(el.name, "0");
           }
+        } else if (el.type === "select-multiple") {
+          const options = el.selectedOptions;
+          for (let o = 0; o < options.length; o++) {
+            const option = options[o];
+            const group = option.parentElement;
+            if (option.disabled) continue;
+            if (group instanceof HTMLOptGroupElement && group.disabled) continue;
+            fd.append(el.name, option.value);
+          }
         } else {
           fd.append(el.name, el.value === "" ? "" : el.value);
         }

data/lib/tina4/public/js/frond.min.js

@@ -1,2 +1,2 @@
-var _frondModule=(()=>{var E=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var q=Object.prototype.hasOwnProperty;var A=(t,s)=>{for(var e in s)E(t,e,{get:s[e],enumerable:!0})},D=(t,s,e,o)=>{if(s&&typeof s=="object"||typeof s=="function")for(let n of H(s))!q.call(t,n)&&n!==e&&E(t,n,{get:()=>s[n],enumerable:!(o=O(s,n))||o.enumerable});return t};var W=t=>D(E({},"__esModule",{value:!0}),t);var z={};A(z,{frond:()=>C});var y=null;function v(t,s){let e;typeof s=="function"?e={onSuccess:s}:e=s||{};let o=(e.method||"GET").toUpperCase(),n=new XMLHttpRequest;if(n.open(o,t,!0),y!==null&&n.setRequestHeader("Authorization","Bearer "+y),e.headers)for(let u in e.headers)Object.prototype.hasOwnProperty.call(e.headers,u)&&n.setRequestHeader(u,e.headers[u]);let c=null;e.body!==void 0&&e.body!==null&&(e.body instanceof FormData?c=e.body:typeof e.body=="object"?(c=JSON.stringify(e.body),n.setRequestHeader("Content-Type","application/json; charset=UTF-8")):typeof e.body=="string"&&(c=e.body,n.setRequestHeader("Content-Type","text/plain; charset=UTF-8"))),n.onload=function(){let u=n.getResponseHeader("FreshToken");u&&u!==""&&(y=u);let r=n.response;try{r=JSON.parse(r)}catch{}if(n.responseURL){let i=new URL(t,window.location.href).href;if(n.responseURL!==i){window.location.href=n.responseURL;return}}n.status>=200&&n.status<400?e.onSuccess&&e.onSuccess(r,n.status,n):e.onError&&e.onError(n.status,n)},n.onerror=function(){e.onError&&e.onError(n.status,n)},e.timeout!==0&&(n.timeout=e.timeout||3e4,n.ontimeout=function(){e.onError&&e.onError(n.status,n)}),n.send(c)}function h(t,s){if(!t)return"";let e=new DOMParser,o=t.includes("<html>")?t:"<body>"+t+"</body></html>",c=e.parseFromString(o,"text/html").querySelector("body"),u=c.querySelectorAll("script");if(u.forEach(function(r){r.remove()}),s!==null){let r=document.getElementById(s);return r&&(c.children.length>0?r.replaceChildren.apply(r,Array.from(c.children)):r.innerHTML=c.innerHTML,u.forEach(function(i){let l=document.createElement("script");l.type="text/javascript",l.async=!0,i.src?l.src=i.src:l.textContent=i.textContent,r.appendChild(l)})),""}return u.forEach(function(r){let i=document.createElement("script");i.type="text/javascript",i.async=!0,i.textContent=r.textContent,document.body.appendChild(i)}),c.innerHTML}function _(t,s,e,o){let n=s||"content";v(t,{method:"GET",onSuccess:function(c,u){if(document.getElementById(n)){let r=h(c,n);e&&e(r,c)}else e&&e(c)},onError:o})}function k(t,s,e,o,n){let c=e||"content";v(t,{method:"POST",body:s,onSuccess:function(u){let r="";if(u&&u.message!==void 0)r=h(u.message,c);else if(document.getElementById(c))r=h(u,c);else{o&&o(u);return}o&&o(r,u)},onError:n})}var x={collect:function(t){let s=new FormData,e=document.querySelectorAll("#"+t+" select, #"+t+" input, #"+t+" textarea");for(let o=0;o<e.length;o++){let n=e[o];if(n.name==="formToken"&&y!==null&&(n.value=y),!!n.name)if(n.type==="file"){let c=n.files;if(c)for(let u=0;u<c.length;u++){let r=c[u];if(r!==void 0){let i=n.name;c.length>1&&!i.includes("[")&&(i=i+"[]"),s.append(i,r,r.name)}}}else n.type==="checkbox"||n.type==="radio"?n.checked?s.append(n.name,n.value):n.type!=="radio"&&s.append(n.name,"0"):s.append(n.name,n.value===""?"":n.value)}return s},submit:function(t,s,e,o,n){let c=x.collect(t);k(s,c,e||"message",o,n)},show:function(t,s,e,o,n){let c=t.toUpperCase();(t==="create"||t==="edit")&&(c="GET"),t==="delete"&&(c="DELETE");let u=e||"form";v(s,{method:c,onSuccess:function(r){let i="";if(r&&r.message!==void 0)i=h(r.message,u);else if(document.getElementById(u))i=h(r,u);else{o&&o(r);return}o&&o(i)},onError:n})}};function M(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,protocols:[],onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",send:function(f){if(!o||o.readyState!==WebSocket.OPEN)throw new Error("[frond] WebSocket is not connected");o.send(typeof f=="string"?f:JSON.stringify(f))},on:function(f,a){return i[f]||(i[f]=[]),i[f].push(a),function(){let d=i[f],g=d.indexOf(a);g>=0&&d.splice(g,1)}},close:function(f,a){n=!0,r&&(clearTimeout(r),r=null),o&&o.close(f||1e3,a||""),l.status="closed"}};function m(f){if(typeof f!="string")return f;try{return JSON.parse(f)}catch{return f}}function p(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,w()},c),c=Math.min(c*2,e.maxReconnectDelay))}function w(){l.status=u>0?"reconnecting":"connecting";try{o=new WebSocket(t,e.protocols)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let f of i.open)f()},o.onmessage=function(f){let a=m(f.data);for(let d of i.message)d(a)},o.onclose=function(f){l.status="closed",e.onClose(f.code,f.reason);for(let a of i.close)a(f.code,f.reason);n||p()},o.onerror=function(f){e.onError(f);for(let a of i.error)a(f)}}return w(),l}function I(t,s){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,events:[],json:!0,onOpen:function(){},onClose:function(){},onError:function(){},...s||{}},o=null,n=!1,c=e.reconnectDelay,u=0,r=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",on:function(a,d){return i[a]||(i[a]=[]),i[a].push(d),function(){let g=i[a],T=g.indexOf(d);T>=0&&g.splice(T,1)}},close:function(){n=!0,r&&(clearTimeout(r),r=null),o&&(o.close(),o=null),l.status="closed"}};function m(a){if(!e.json)return a;try{return JSON.parse(a)}catch{return a}}function p(a,d){for(let g of i.message)g(a,d||void 0)}function w(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",r=setTimeout(function(){r=null,f()},c),c=Math.min(c*2,e.maxReconnectDelay))}function f(){l.status=u>0?"reconnecting":"connecting";try{o=new EventSource(t)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let a of i.open)a(null)},o.onmessage=function(a){p(m(a.data),null)};for(let a of e.events)o.addEventListener(a,function(d){p(m(d.data),a)});o.onerror=function(a){e.onError(a);for(let d of i.error)d(a);if(o&&o.readyState===2){o=null,l.status="closed",e.onClose();for(let d of i.close)d(null);n||w()}}}return f(),l}var U={set:function(t,s,e){let o="";if(e){let n=new Date;n.setTime(n.getTime()+e*24*60*60*1e3),o="; expires="+n.toUTCString()}document.cookie=t+"="+(s||"")+o+"; path=/"},get:function(t){let s=t+"=",e=document.cookie.split(";");for(let o=0;o<e.length;o++){let n=e[o];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(s)===0)return n.substring(s.length)}return null},remove:function(t){document.cookie=t+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/"}};function j(t,s){let e=document.getElementById("message");if(!e)return;let o=s||"info";e.innerHTML='<div class="alert alert-'+o+' alert-dismissible">'+t+'<button type="button" class="btn-close" data-t4-dismiss="alert">&times;</button></div>'}function X(t,s,e,o){let n=window.screenLeft!==void 0?window.screenLeft:window.screenX,c=window.screenTop!==void 0?window.screenTop:window.screenY,u=window.innerWidth||document.documentElement.clientWidth||screen.width,r=window.innerHeight||document.documentElement.clientHeight||screen.height,i=u/window.screen.availWidth,l=(u-e)/2/i+n,m=(r-o)/2/i+c,p=window.open(t,s,"directories=no,toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width="+e/i+",height="+o/i+",top="+m+",left="+l);return window.focus&&p&&p.focus(),p}function B(t){if(t.indexOf("No data available")>=0){window.alert("No data available for this report.");return}window.open(t,"_blank","toolbar=no,scrollbars=yes,resizable=yes,width=800,height=600,top=0,left=0")}function P(t,s,e,o){v(t,{method:"POST",body:{query:s,variables:e||{}},onSuccess:function(n){o&&o(n.data||null,n.errors||void 0)},onError:function(n){o&&o(null,[{message:"GraphQL request failed with status "+n}])}})}function b(t){let s=t.dataset;return s&&s.key?s.key:null}function F(t,s){let e=s.attributes;for(let n=0;n<e.length;n++){let c=e[n];t.getAttribute(c.name)!==c.value&&t.setAttribute(c.name,c.value)}Array.prototype.slice.call(t.attributes).forEach(function(n){s.hasAttribute(n.name)||t.removeAttribute(n.name)})}function G(t,s){let e=s.tagName;e==="INPUT"||e==="TEXTAREA"||e==="SELECT"||(F(t,s),t.children.length||s.children.length?L(t,s):t.innerHTML!==s.innerHTML&&(t.innerHTML=s.innerHTML))}function L(t,s){let e=Array.prototype.slice.call(t.children),o=Array.prototype.slice.call(s.children),n={};e.forEach(function(r){let i=b(r);i&&(n[i]=r)});let c=[];for(let r=0;r<o.length;r++){let i=o[r],l=b(i),m=null;l&&n[l]?m=n[l]:!l&&e[r]&&!b(e[r])&&e[r].tagName===i.tagName&&(m=e[r]),m&&m.tagName===i.tagName?(G(m,i),reused.push(m),c.push(m)):c.push(i)}let u=t.firstElementChild;for(let r=0;r<c.length;r++){let i=c[r];i===u?u=u.nextElementSibling:t.insertBefore(i,u)}e.forEach(function(r){c.indexOf(r)===-1&&r.parentNode===t&&t.removeChild(r)}),reused}function R(t,s){let e=document.createElement("div");if(e.innerHTML=s,!e.children.length||!t.children.length){t.innerHTML=s;return}L(t,e)}function J(t){return/^wss?:\/\//.test(t)?t:(typeof location<"u"&&location.protocol==="https:"?"wss":"ws")+"://"+location.host+t}function N(t,s){return t&&typeof t=="object"?t.type==="live"?s&&t.name&&t.name!==s?null:t.html!=null?String(t.html):null:null:typeof t=="string"?t:null}function S(t){if(typeof document>"u")return;let e=(t||document).querySelectorAll("[data-frond-live]");Array.prototype.slice.call(e).forEach(function(o){if(o.__frondLive)return;o.__frondLive=!0;let n=o.getAttribute("data-mode"),c=o.getAttribute("data-frond-live");if(n==="poll"){let u=o.getAttribute("data-src"),r=(parseInt(o.getAttribute("data-interval"),10)||5)*1e3,i=setInterval(function(){typeof document<"u"&&document.hidden||v(u,{method:"GET",onSuccess:function(l){R(o,typeof l=="string"?l:String(l))}})},r);o.__frondLiveStop=function(){clearInterval(i)}}else if(n==="ws"){let u=M(J(o.getAttribute("data-ws")));u.on("message",function(r){let i=N(r,c);i!==null&&R(o,i)}),o.__frondLiveStop=function(){u.close()}}else n==="sse"&&typeof console<"u"&&console.warn&&console.warn("[frond.live] sse transport is not wired yet (v1 supports poll and ws); block '"+c+"' shows first paint only. Use poll or ws.")})}var C={request:v,load:_,post:k,inject:h,form:x,ws:M,sse:I,live:S,cookie:U,message:j,popup:X,report:B,graphql:P,get token(){return y},set token(t){y=t}};typeof window<"u"&&(window.frond=C,typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){S()}):S()));return W(z);})();
+var _frondModule=(()=>{var E=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var D=(t,r)=>{for(var e in r)E(t,e,{get:r[e],enumerable:!0})},_=(t,r,e,o)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of q(r))!A.call(t,n)&&n!==e&&E(t,n,{get:()=>r[n],enumerable:!(o=H(r,n))||o.enumerable});return t};var W=t=>_(E({},"__esModule",{value:!0}),t);var K={};D(K,{frond:()=>C});var v=null;function R(t){try{return new URL(t,window.location.href).origin===window.location.origin}catch{return!1}}function h(t,r){let e;typeof r=="function"?e={onSuccess:r}:e=r||{};let o=(e.method||"GET").toUpperCase(),n=new XMLHttpRequest;n.open(o,t,!0);let c=R(t);if(v!==null&&c&&n.setRequestHeader("Authorization","Bearer "+v),e.headers)for(let s in e.headers)Object.prototype.hasOwnProperty.call(e.headers,s)&&n.setRequestHeader(s,e.headers[s]);let u=null;e.body!==void 0&&e.body!==null&&(e.body instanceof FormData?u=e.body:typeof e.body=="object"?(u=JSON.stringify(e.body),n.setRequestHeader("Content-Type","application/json; charset=UTF-8")):typeof e.body=="string"&&(u=e.body,n.setRequestHeader("Content-Type","text/plain; charset=UTF-8"))),n.onload=function(){let s=n.getResponseHeader("FreshToken"),i=c&&(!n.responseURL||R(n.responseURL));s&&s!==""&&i&&(v=s);let l=n.response;try{l=JSON.parse(l)}catch{}if(n.responseURL){let f=new URL(t,window.location.href).href;if(n.responseURL!==f){window.location.href=n.responseURL;return}}n.status>=200&&n.status<400?e.onSuccess&&e.onSuccess(l,n.status,n):e.onError&&e.onError(n.status,n)},n.onerror=function(){e.onError&&e.onError(n.status,n)},e.timeout!==0&&(n.timeout=e.timeout||3e4,n.ontimeout=function(){e.onError&&e.onError(n.status,n)}),n.send(u)}function y(t,r){if(!t)return"";let e=new DOMParser,o=t.includes("<html>")?t:"<body>"+t+"</body></html>",c=e.parseFromString(o,"text/html").querySelector("body"),u=c.querySelectorAll("script");if(u.forEach(function(s){s.remove()}),r!==null){let s=document.getElementById(r);return s&&(c.children.length>0?s.replaceChildren.apply(s,Array.from(c.children)):s.innerHTML=c.innerHTML,u.forEach(function(i){let l=document.createElement("script");l.type="text/javascript",l.async=!0,i.src?l.src=i.src:l.textContent=i.textContent,s.appendChild(l)})),""}return u.forEach(function(s){let i=document.createElement("script");i.type="text/javascript",i.async=!0,i.textContent=s.textContent,document.body.appendChild(i)}),c.innerHTML}function U(t,r,e,o){let n=r||"content";h(t,{method:"GET",onSuccess:function(c,u){if(document.getElementById(n)){let s=y(c,n);e&&e(s,c)}else e&&e(c)},onError:o})}function L(t,r,e,o,n){let c=e||"content";h(t,{method:"POST",body:r,onSuccess:function(u){let s="";if(u&&u.message!==void 0)s=y(u.message,c);else if(document.getElementById(c))s=y(u,c);else{o&&o(u);return}o&&o(s,u)},onError:n})}var M={collect:function(t){let r=new FormData,e=document.querySelectorAll("#"+t+" select, #"+t+" input, #"+t+" textarea");for(let o=0;o<e.length;o++){let n=e[o];if(n.name)if(n.type==="file"){let c=n.files;if(c)for(let u=0;u<c.length;u++){let s=c[u];if(s!==void 0){let i=n.name;c.length>1&&!i.includes("[")&&(i=i+"[]"),r.append(i,s,s.name)}}}else if(n.type==="checkbox"||n.type==="radio")n.checked?r.append(n.name,n.value):n.type!=="radio"&&r.append(n.name,"0");else if(n.type==="select-multiple"){let c=n.selectedOptions;for(let u=0;u<c.length;u++){let s=c[u],i=s.parentElement;s.disabled||i instanceof HTMLOptGroupElement&&i.disabled||r.append(n.name,s.value)}}else r.append(n.name,n.value===""?"":n.value)}return r},submit:function(t,r,e,o,n){let c=M.collect(t);L(r,c,e||"message",o,n)},show:function(t,r,e,o,n){let c=t.toUpperCase();(t==="create"||t==="edit")&&(c="GET"),t==="delete"&&(c="DELETE");let u=e||"form";h(r,{method:c,onSuccess:function(s){let i="";if(s&&s.message!==void 0)i=y(s.message,u);else if(document.getElementById(u))i=y(s,u);else{o&&o(s);return}o&&o(i)},onError:n})}};function x(t,r){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,protocols:[],onOpen:function(){},onClose:function(){},onError:function(){},...r||{}},o=null,n=!1,c=e.reconnectDelay,u=0,s=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",send:function(d){if(!o||o.readyState!==WebSocket.OPEN)throw new Error("[frond] WebSocket is not connected");o.send(typeof d=="string"?d:JSON.stringify(d))},on:function(d,a){return i[d]||(i[d]=[]),i[d].push(a),function(){let p=i[d],g=p.indexOf(a);g>=0&&p.splice(g,1)}},close:function(d,a){n=!0,s&&(clearTimeout(s),s=null),o&&o.close(d||1e3,a||""),l.status="closed"}};function f(d){if(typeof d!="string")return d;try{return JSON.parse(d)}catch{return d}}function m(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",s=setTimeout(function(){s=null,w()},c),c=Math.min(c*2,e.maxReconnectDelay))}function w(){l.status=u>0?"reconnecting":"connecting";try{o=new WebSocket(t,e.protocols)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let d of i.open)d()},o.onmessage=function(d){let a=f(d.data);for(let p of i.message)p(a)},o.onclose=function(d){l.status="closed",e.onClose(d.code,d.reason);for(let a of i.close)a(d.code,d.reason);n||m()},o.onerror=function(d){e.onError(d);for(let a of i.error)a(d)}}return w(),l}function I(t,r){let e={reconnect:!0,reconnectDelay:1e3,maxReconnectDelay:3e4,maxReconnectAttempts:1/0,events:[],json:!0,onOpen:function(){},onClose:function(){},onError:function(){},...r||{}},o=null,n=!1,c=e.reconnectDelay,u=0,s=null,i={message:[],open:[],close:[],error:[]},l={status:"connecting",on:function(a,p){return i[a]||(i[a]=[]),i[a].push(p),function(){let g=i[a],T=g.indexOf(p);T>=0&&g.splice(T,1)}},close:function(){n=!0,s&&(clearTimeout(s),s=null),o&&(o.close(),o=null),l.status="closed"}};function f(a){if(!e.json)return a;try{return JSON.parse(a)}catch{return a}}function m(a,p){for(let g of i.message)g(a,p||void 0)}function w(){!e.reconnect||u>=e.maxReconnectAttempts||(u++,l.status="reconnecting",s=setTimeout(function(){s=null,d()},c),c=Math.min(c*2,e.maxReconnectDelay))}function d(){l.status=u>0?"reconnecting":"connecting";try{o=new EventSource(t)}catch{l.status="closed";return}o.onopen=function(){l.status="open",u=0,c=e.reconnectDelay,e.onOpen();for(let a of i.open)a(null)},o.onmessage=function(a){m(f(a.data),null)};for(let a of e.events)o.addEventListener(a,function(p){m(f(p.data),a)});o.onerror=function(a){e.onError(a);for(let p of i.error)p(a);if(o&&o.readyState===2){o=null,l.status="closed",e.onClose();for(let p of i.close)p(null);n||w()}}}return d(),l}var j={set:function(t,r,e){let o="";if(e){let n=new Date;n.setTime(n.getTime()+e*24*60*60*1e3),o="; expires="+n.toUTCString()}document.cookie=t+"="+(r||"")+o+"; path=/"},get:function(t){let r=t+"=",e=document.cookie.split(";");for(let o=0;o<e.length;o++){let n=e[o];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(r)===0)return n.substring(r.length)}return null},remove:function(t){document.cookie=t+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/"}};function X(t,r){let e=document.getElementById("message");if(!e)return;let o=r||"info";e.innerHTML='<div class="alert alert-'+o+' alert-dismissible">'+t+'<button type="button" class="btn-close" data-t4-dismiss="alert">&times;</button></div>'}function B(t,r,e,o){let n=window.screenLeft!==void 0?window.screenLeft:window.screenX,c=window.screenTop!==void 0?window.screenTop:window.screenY,u=window.innerWidth||document.documentElement.clientWidth||screen.width,s=window.innerHeight||document.documentElement.clientHeight||screen.height,i=u/window.screen.availWidth,l=(u-e)/2/i+n,f=(s-o)/2/i+c,m=window.open(t,r,"directories=no,toolbar=no,location=no,status=no,menubar=no,scrollbars=yes,resizable=yes,width="+e/i+",height="+o/i+",top="+f+",left="+l);return window.focus&&m&&m.focus(),m}function P(t){if(t.indexOf("No data available")>=0){window.alert("No data available for this report.");return}window.open(t,"_blank","toolbar=no,scrollbars=yes,resizable=yes,width=800,height=600,top=0,left=0")}function F(t,r,e,o){h(t,{method:"POST",body:{query:r,variables:e||{}},onSuccess:function(n){o&&o(n.data||null,n.errors||void 0)},onError:function(n){o&&o(null,[{message:"GraphQL request failed with status "+n}])}})}function b(t){let r=t.dataset;return r&&r.key?r.key:null}function G(t,r){let e=r.attributes;for(let n=0;n<e.length;n++){let c=e[n];t.getAttribute(c.name)!==c.value&&t.setAttribute(c.name,c.value)}Array.prototype.slice.call(t.attributes).forEach(function(n){r.hasAttribute(n.name)||t.removeAttribute(n.name)})}function J(t,r){let e=r.tagName;e==="INPUT"||e==="TEXTAREA"||e==="SELECT"||(G(t,r),t.children.length||r.children.length?O(t,r):t.innerHTML!==r.innerHTML&&(t.innerHTML=r.innerHTML))}function O(t,r){let e=Array.prototype.slice.call(t.children),o=Array.prototype.slice.call(r.children),n={};e.forEach(function(s){let i=b(s);i&&(n[i]=s)});let c=[];for(let s=0;s<o.length;s++){let i=o[s],l=b(i),f=null;l&&n[l]?f=n[l]:!l&&e[s]&&!b(e[s])&&e[s].tagName===i.tagName&&(f=e[s]),f&&f.tagName===i.tagName?(J(f,i),reused.push(f),c.push(f)):c.push(i)}let u=t.firstElementChild;for(let s=0;s<c.length;s++){let i=c[s];i===u?u=u.nextElementSibling:t.insertBefore(i,u)}e.forEach(function(s){c.indexOf(s)===-1&&s.parentNode===t&&t.removeChild(s)}),reused}function k(t,r){let e=document.createElement("div");if(e.innerHTML=r,!e.children.length||!t.children.length){t.innerHTML=r;return}O(t,e)}function N(t){return/^wss?:\/\//.test(t)?t:(typeof location<"u"&&location.protocol==="https:"?"wss":"ws")+"://"+location.host+t}function z(t,r){return t&&typeof t=="object"?t.type==="live"?r&&t.name&&t.name!==r?null:t.html!=null?String(t.html):null:null:typeof t=="string"?t:null}function S(t){if(typeof document>"u")return;let e=(t||document).querySelectorAll("[data-frond-live]");Array.prototype.slice.call(e).forEach(function(o){if(o.__frondLive)return;o.__frondLive=!0;let n=o.getAttribute("data-mode"),c=o.getAttribute("data-frond-live");if(n==="poll"){let u=o.getAttribute("data-src"),s=(parseInt(o.getAttribute("data-interval"),10)||5)*1e3,i=setInterval(function(){typeof document<"u"&&document.hidden||h(u,{method:"GET",onSuccess:function(l){k(o,typeof l=="string"?l:String(l))}})},s);o.__frondLiveStop=function(){clearInterval(i)}}else if(n==="ws"){let u=x(N(o.getAttribute("data-ws")));u.on("message",function(s){let i=z(s,c);i!==null&&k(o,i)}),o.__frondLiveStop=function(){u.close()}}else n==="sse"&&typeof console<"u"&&console.warn&&console.warn("[frond.live] sse transport is not wired yet (v1 supports poll and ws); block '"+c+"' shows first paint only. Use poll or ws.")})}var C={request:h,load:U,post:L,inject:y,form:M,ws:x,sse:I,live:S,cookie:j,message:X,popup:B,report:P,graphql:F,get token(){return v},set token(t){v=t}};typeof window<"u"&&(window.frond=C,typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){S()}):S()));return W(K);})();
 /* Frond v2.2.0 - tina4.com */

data/lib/tina4/query_builder.rb

@@ -186,6 +186,38 @@ module Tina4
       self
     end
 
+    # Set OFFSET (rows to skip) as its own chainable verb.
+    #
+    # `limit(n, offset)` buries the offset as a second positional arg; this
+    # exposes it on its own, so `.offset(20).limit(10)` reads naturally and
+    # matches the SQL keyword.
+    #
+    # @param count [Integer] Number of rows to skip.
+    # @return [self]
+    def offset(count)
+      @offset_val = count
+      self
+    end
+
+    # Alias for {#offset} — the Mongo/Eloquent name for the same thing.
+    #
+    # Mirrors the DocStore cursor's `skip` and the `:skip` key that {#to_mongo}
+    # already emits, so a query reads the same whether it targets SQL or MongoDB.
+    #
+    # @param count [Integer] Number of rows to skip.
+    # @return [self]
+    def skip(count)
+      offset(count)
+    end
+
+    # Alias for {#limit} — the Eloquent name; pairs with {#skip}.
+    #
+    # @param count [Integer] Maximum rows to return.
+    # @return [self]
+    def take(count)
+      limit(count)
+    end
+
     # Build and return the SQL string without executing.
     #
     # @return [String] The constructed SQL query.

data/lib/tina4/queue_backends/kafka_backend.rb

@@ -42,6 +42,11 @@ module Tina4
         }.merge(security)
         @consumer = Rdkafka::Config.new(consumer_config).consumer
         @subscribed_topics = []
+        # Records polled but not yet acknowledged, keyed by the id the Queue
+        # hands back to acknowledge(), valued by the rdkafka message (its
+        # topic/partition/offset). acknowledge() commits exactly THAT record's
+        # offset, never a single "last message" slot (ADR-0022 decision 3).
+        @in_flight = {}
       rescue LoadError
         raise "Kafka backend requires the 'rdkafka' gem. Install with: gem install rdkafka"
       end
@@ -157,12 +162,28 @@ module Tina4
         return nil unless msg
 
         data = Tina4.parse_json(msg.payload)
-        @last_message = msg
+        coordinate = "#{topic}:#{msg.partition}:#{msg.offset}"
+
+        # A record carrying a "payload" key is a Tina4 envelope: keep its own id
+        # (falling back to the coordinate) and carry attempts/error back so a
+        # redelivery does not reset the count and re-produce a poison record
+        # forever. A record WITHOUT one is externally produced (Debezium/CDC and
+        # friends, no envelope, no id -- tina4#274): its whole value IS the
+        # payload, and the coordinate becomes its id. Either way the job gets the
+        # id acknowledge() maps back to this record's offset.
+        job =
+          if data.is_a?(Hash) && data.key?("payload")
+            id = data["id"].to_s.empty? ? coordinate : data["id"]
+            Tina4::Job.new(
+              topic: topic, payload: data["payload"], id: id,
+              attempts: data["attempts"] || 0, error: data["error"]
+            )
+          else
+            Tina4::Job.new(topic: topic, payload: data, id: coordinate, attempts: 0)
+          end
 
-        # attempts and error MUST be carried back (Job.from_payload does this);
-        # rebuilding from topic/payload/id alone reset attempts to 0 on every
-        # redelivery, so a poison record would be re-produced forever.
-        Tina4::Job.from_payload(data)
+        @in_flight[job.id.to_s] = msg
+        job
       rescue Rdkafka::RdkafkaError
         nil
       end
@@ -177,8 +198,19 @@ module Tina4
         0
       end
 
-      def acknowledge(_message)
-        @consumer.commit if @last_message
+      # Commit the offset JUST PAST the acknowledged record so the group never
+      # re-reads it, even across a restart (ADR-0022 decisions 2 + 4). The offset
+      # is committed for the specific record dequeue() tracked against this job's
+      # id -- NOT a bare @consumer.commit of the whole polled position, which
+      # would commit past records still in flight when jobs are completed out of
+      # order (decision 3). A job never dequeued (or already acked) is a no-op.
+      def acknowledge(message)
+        msg = @in_flight.delete(message.id.to_s)
+        return unless msg
+
+        tpl = Rdkafka::Consumer::TopicPartitionList.new
+        tpl.add_topic_and_partitions_with_offsets(msg.topic, msg.partition => msg.offset + 1)
+        @consumer.commit(tpl, false)
       end
 
       def requeue(message)

data/lib/tina4/shutdown.rb

@@ -106,10 +106,21 @@ module Tina4
       # otherwise leak on every single shutdown.
       def release_resources
         close_websockets
+        stop_tcp_services
         stop_background_tasks
         close_database
       end
 
+      # Drain live raw TCP service connections (feature 142) within the deadline,
+      # firing their on_close handlers, alongside the HTTP/WebSocket drain.
+      def stop_tcp_services
+        return unless defined?(Tina4::Tcp)
+
+        Tina4::Tcp.drain_all(timeout: @timeout.to_f)
+      rescue StandardError => e
+        Tina4::Log.error("Error draining TCP services: #{e.message}")
+      end
+
       # Block until initiate_shutdown has finished every teardown step.
       #
       # stop_accepting unblocks the built-in server's accept loop immediately, so
@@ -158,6 +169,8 @@ module Tina4
         return unless @server.respond_to?(:shutdown)
 
         @server.shutdown
+        # Raw TCP listeners stop accepting at the same moment as HTTP.
+        Tina4::Tcp.stop_accepting_all if defined?(Tina4::Tcp)
         Tina4::Log.info("Stopped accepting new connections")
       rescue StandardError => e
         Tina4::Log.error("Error closing the listening socket: #{e.message}")

data/lib/tina4/tcp.rb

@@ -0,0 +1,573 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+require "socket"
+
+module Tina4
+  # Raw TCP service — a user-facing, non-HTTP, long-lived binary TCP listener.
+  #
+  # Governed by ADR-0102 (feature 142), and the Python reference
+  # tina4_python/tcp. A Tina4 app exposes its own protocol — a GPS/GPRS
+  # car-tracker gateway (GT06/TK103/Concox/Teltonika) is the driving case — in
+  # the SAME process as its HTTP dashboard, reusing config, logging, ORM and
+  # queue.
+  #
+  #   svc = Tina4::Tcp.service(5023, idle_timeout: 0, max_connections: 5000)
+  #   svc.on_data do |conn, data|
+  #     frame = parse(data)                 # the APP frames the stream
+  #     conn.identify(frame.imei) if frame.login?
+  #     conn.send(ack_for(frame))           # ACK on the same socket
+  #   end
+  #
+  #   # server -> device push from an HTTP route:
+  #   Tina4::Tcp.get.send_to(imei, build_command("set_interval", 30))
+  #
+  # Ruby's thread-per-connection model satisfies D1 (in-process): the acceptor
+  # thread runs in the SAME VM as the HTTP server, so the device gateway and its
+  # dashboard share one process. The framework owns the socket hard-parts:
+  # lifecycle, max_connections refusal, an idle reaper (default OFF for
+  # long-lived device sockets), graceful-shutdown drain, bounded write
+  # backpressure, and single-owner bind under N workers.
+  #
+  # Non-goals in v1 (ADR-0102): no CRC/length framing helper beyond on_line, no
+  # TLS termination, no UDP, no replacement for the WebSocket surface.
+
+  # One live TCP connection — the uniform connection object (ADR-0102 D5). The
+  # SAME surface exists in all four frameworks so the primitive ports.
+  class TcpConnection
+    # The raw TCP peer address ("127.0.0.1:54321"), never a forwarded header.
+    attr_reader :remote_addr
+    # Per-connection mutable state bag — the app's parse buffer, auth flag.
+    attr_accessor :context
+    attr_reader :socket
+    # Stable registry key: the fd number captured at construction (see below).
+    attr_reader :fileno
+
+    def initialize(socket, service, remote_addr)
+      @socket = socket
+      # Cache the fd number now: once the socket is closed, #fileno raises
+      # IOError, and the registry still needs a stable key to remove by.
+      @fileno = begin
+        socket.fileno
+      rescue IOError, SystemCallError
+        nil
+      end
+      @service = service
+      @remote_addr = remote_addr
+      @id = nil                 # the registry id (IMEI), nil until identify
+      @context = {}
+      @closed = false
+      @close_fired = false
+      @last_activity = monotonic
+      @pending = +"".b
+      @line_buffer = +"".b
+      @write_lock = Mutex.new
+    end
+
+    # The registry id (the IMEI), or nil until identify is called.
+    def id
+      @id
+    end
+
+    def closed?
+      @closed
+    end
+
+    def last_activity
+      @last_activity
+    end
+
+    def touch
+      @last_activity = monotonic
+    end
+
+    # Accessors the service's reader loop uses for on_line buffering.
+    def line_buffer
+      @line_buffer
+    end
+
+    def line_buffer=(value)
+      @line_buffer = value
+    end
+
+    # Register this live connection under an app-chosen id (the IMEI). A second
+    # connection identifying with the same id SUPERSEDES the first in the
+    # registry — exactly a device that dropped and reconnected.
+    def identify(app_id)
+      @id = app_id.to_s
+      @service.register_id(@id, self)
+      self
+    end
+
+    # Write raw bytes to THIS socket. Returns true when queued/sent, false when
+    # the connection is closed or dropped for backpressure. A stalled reader
+    # (never draining) is bounded: once more than the service's max_backlog
+    # bytes are outstanding, the connection is dropped rather than buffered
+    # without end (mirrors the WebSocket TINA4_WS_MAX_BACKLOG posture).
+    def send(data)
+      return false if @closed
+
+      bytes = data.to_s.dup.force_encoding(Encoding::BINARY)
+      overflow = false
+      @write_lock.synchronize do
+        @pending << bytes
+        flush_pending
+        limit = @service.max_backlog
+        overflow = (limit.positive? && @pending.bytesize > limit)
+      end
+      return false if @closed
+
+      if overflow
+        Tina4::Log.warning(
+          "tcp_service '#{@service.name}': dropping a stalled reader — " \
+          "#{@pending.bytesize} bytes queued exceeds the #{@service.max_backlog}-byte backlog limit"
+        )
+        close
+        return false
+      end
+      true
+    end
+
+    # Flush the per-connection queue without blocking. Caller holds @write_lock.
+    def flush_pending
+      return if @socket.nil? || @pending.empty?
+
+      until @pending.empty?
+        written = @socket.write_nonblock(@pending, exception: false)
+        break if written == :wait_writable
+
+        @pending = @pending.byteslice(written..) || +"".b
+      end
+    rescue IOError, SystemCallError
+      @closed = true
+      close_socket
+    end
+
+    # Opportunistic flush from the reader loop (acquires the lock).
+    def try_flush
+      return if @closed
+
+      @write_lock.synchronize { flush_pending }
+    end
+
+    # Close this connection. on_close fires exactly once (from the service's
+    # removal path) and the registry entry is removed.
+    def close
+      return if @closed
+
+      @closed = true
+      close_socket
+      @service.remove(self)
+    end
+
+    # Fire on_close exactly once. Called by the service when the connection
+    # leaves (peer close, server close, reap, or drain).
+    def fire_close
+      return if @close_fired
+
+      @close_fired = true
+      @closed = true
+      handler = @service.callback(:on_close)
+      return if handler.nil?
+
+      begin
+        handler.call(self)
+      rescue StandardError => e
+        Tina4::Log.error("tcp_service '#{@service.name}' on_close error: #{e.message}")
+      end
+    end
+
+    private
+
+    def close_socket
+      # Shut the socket down before closing so the peer sees EOF immediately.
+      # A plain close is enough on macOS, but on Linux the FIN can be deferred
+      # while the reader thread still holds the fd in IO.select, so the client
+      # never observes end-of-stream. shutdown(SHUT_RDWR) forces it.
+      @socket&.shutdown(Socket::SHUT_RDWR)
+    rescue IOError, SystemCallError
+      nil
+    ensure
+      begin
+        @socket&.close
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  # A named raw TCP listener and its connection registry (ADR-0102).
+  class TcpService
+    READ_CHUNK = 65_536
+
+    attr_reader :name, :port
+
+    def initialize(port, name: "default", on_connect: nil, on_data: nil,
+                   on_close: nil, on_line: nil, idle_timeout: 0,
+                   max_connections: nil, max_backlog: nil, &block)
+      @port = Integer(port)
+      @name = name.to_s
+      @callbacks = {
+        on_connect: on_connect,
+        on_data: on_data || block, # a bare block is the on_data handler
+        on_close: on_close,
+        on_line: on_line
+      }
+      # Default OFF: tracker sockets are deliberately long-lived and mostly idle
+      # between location packets, so a default reaper would kill healthy devices.
+      @idle_timeout = idle_timeout.to_f
+      @max_connections = max_connections.nil? ? nil : Integer(max_connections)
+      @max_backlog = self.class.resolve_max_backlog(max_backlog)
+
+      @connections = {}     # socket.fileno => TcpConnection
+      @by_id = {}           # app_id => TcpConnection
+      @mutex = Mutex.new
+      @server = nil
+      @owner = false
+      @bound_port = nil
+      @acceptor = nil
+      @readers = {}         # object_id => Thread
+      @running = false
+    end
+
+    def self.resolve_max_backlog(explicit)
+      default = 1 << 20 # 1 MiB
+      return (explicit.to_i.positive? ? explicit.to_i : default) unless explicit.nil?
+
+      raw = (ENV["TINA4_TCP_MAX_BACKLOG"] || "").strip
+      return default if raw.empty?
+
+      value = raw.to_i
+      value.positive? ? value : default
+    end
+
+    def max_backlog
+      @max_backlog
+    end
+
+    def callback(event)
+      @callbacks[event]
+    end
+
+    def owner?
+      @owner
+    end
+
+    def bound_port
+      @bound_port || @port
+    end
+
+    def count
+      @mutex.synchronize { @connections.size }
+    end
+
+    # ── Decorator-style setters (parity with the Python @svc.on_* handlers) ──
+
+    def on_connect(&block) = set_callback(:on_connect, block)
+    def on_data(&block) = set_callback(:on_data, block)
+    def on_close(&block) = set_callback(:on_close, block)
+    def on_line(&block) = set_callback(:on_line, block)
+
+    # ── Registry (D4 — server -> device push) ──────────────────────────────
+
+    def register_id(app_id, conn)
+      @mutex.synchronize { @by_id[app_id] = conn } # supersede: the live one wins
+    end
+
+    # The live connection for an app id, or nil if unknown or closed.
+    def connection(app_id)
+      conn = @mutex.synchronize { @by_id[app_id.to_s] }
+      return nil if conn.nil? || conn.closed?
+
+      conn
+    end
+
+    # Write bytes to exactly the connection identified by app_id. A send to an
+    # unknown or closed id is a NO-OP that returns false — never a raise.
+    def send_to(app_id, data)
+      conn = connection(app_id)
+      return false if conn.nil?
+
+      conn.send(data)
+    end
+
+    # Write bytes to every live connection. Returns how many received it.
+    def broadcast(data)
+      conns = @mutex.synchronize { @connections.values.dup }
+      conns.count { |conn| conn.send(data) }
+    end
+
+    # ── Lifecycle ────────────────────────────────────────────────────────────
+
+    # Bind the listener on host:port and start accepting on a dedicated thread.
+    # SO_REUSEPORT is OFF, so under a multi-worker deployment exactly ONE worker
+    # wins the bind; a worker that finds the port already bound skips silently
+    # (single-owner, D1). Returns true when THIS call bound the port.
+    def start(host = "0.0.0.0")
+      return @owner unless @server.nil?
+
+      begin
+        @server = TCPServer.new(host, @port)
+      rescue Errno::EADDRINUSE, Errno::EADDRNOTAVAIL => e
+        @owner = false
+        Tina4::Log.info(
+          "tcp_service '#{@name}' port #{@port} is already bound by another worker — " \
+          "single-owner, this worker will not bind (#{e.class})"
+        )
+        return false
+      end
+      @owner = true
+      @running = true
+      @bound_port = @server.addr[1]
+      Tina4::Log.info("tcp_service '#{@name}' listening on #{host}:#{@bound_port}")
+      @acceptor = Thread.new { accept_loop }
+      true
+    end
+
+    # Stop accepting new connections (close the listener). Live connections stay.
+    def stop_accepting
+      @running = false
+      srv = @server
+      @server = nil
+      srv&.close
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    # Close every live connection (firing on_close) and release the listener.
+    def drain(timeout: 5.0)
+      stop_accepting
+      @acceptor&.join(timeout)
+      conns = @mutex.synchronize { @connections.values.dup }
+      conns.each(&:close)
+      readers = @mutex.synchronize { @readers.values.dup }
+      deadline = monotonic + timeout
+      readers.each do |thread|
+        remaining = deadline - monotonic
+        thread.join(remaining.positive? ? remaining : 0)
+      end
+    end
+
+    alias stop drain
+
+    # Remove a connection from the registry and fire on_close exactly once.
+    # Called by TcpConnection#close and by the reader loop on EOF.
+    def remove(conn)
+      tracked = false
+      @mutex.synchronize do
+        key = conn.fileno
+        if key && @connections[key].equal?(conn)
+          @connections.delete(key)
+          tracked = true
+        else
+          found = @connections.key(conn)
+          unless found.nil?
+            @connections.delete(found)
+            tracked = true
+          end
+        end
+        # Only drop the id when THIS connection still owns it; a newer
+        # connection that superseded it keeps the id.
+        @by_id.delete(conn.id) if conn.id && @by_id[conn.id].equal?(conn)
+      end
+      conn.fire_close if tracked
+    end
+
+    private
+
+    def set_callback(event, block)
+      @callbacks[event] = block if block
+      self
+    end
+
+    def accept_loop
+      while @running
+        begin
+          socket = @server&.accept
+        rescue IOError, Errno::EBADF, Errno::ECONNABORTED
+          break # listener closed by stop_accepting
+        end
+        break if socket.nil?
+
+        handle_accept(socket)
+      end
+    rescue StandardError => e
+      Tina4::Log.error("tcp_service '#{@name}' accept loop error: #{e.message}")
+    end
+
+    def handle_accept(socket)
+      # Refuse past the limit BEFORE the connection joins the registry.
+      over_limit = @mutex.synchronize do
+        !@max_connections.nil? && @connections.size >= @max_connections
+      end
+      if over_limit
+        socket.close rescue nil
+        return
+      end
+
+      conn = TcpConnection.new(socket, self, peer_address(socket))
+      @mutex.synchronize { @connections[conn.fileno] = conn }
+
+      fire(:on_connect, conn)
+
+      reader = Thread.new { reader_loop(conn) }
+      @mutex.synchronize { @readers[conn.object_id] = reader }
+    end
+
+    def reader_loop(conn)
+      socket = conn.socket
+      line_handler = @callbacks[:on_line]
+      sweep = @idle_timeout.positive? ? [@idle_timeout / 2.0, 1.0].min.clamp(0.05, 1.0) : nil
+      loop do
+        break if conn.closed?
+
+        ready = IO.select([socket], nil, nil, sweep)
+        if ready.nil?
+          # Idle sweep: close a connection silent past the timeout.
+          if @idle_timeout.positive? && (monotonic - conn.last_activity) >= @idle_timeout
+            conn.close
+            break
+          end
+          next
+        end
+
+        data = socket.read_nonblock(READ_CHUNK, exception: false)
+        next if data == :wait_readable
+        break if data.nil? # EOF — peer closed
+
+        conn.touch
+        dispatch_data(conn, data, line_handler)
+        conn.try_flush
+      end
+    rescue IOError, EOFError, Errno::ECONNRESET, Errno::EBADF
+      nil
+    rescue StandardError => e
+      Tina4::Log.error("tcp_service '#{@name}' handler error: #{e.message}")
+    ensure
+      @mutex.synchronize { @readers.delete(conn.object_id) }
+      remove(conn)
+    end
+
+    def dispatch_data(conn, data, line_handler)
+      on_data = @callbacks[:on_data]
+      # Raw bytes, exactly as received — never newline-split, never decoded.
+      if on_data
+        begin
+          on_data.call(conn, data)
+        rescue StandardError => e
+          Tina4::Log.error("tcp_service '#{@name}' on_data error: #{e.message}")
+        end
+      end
+
+      return unless line_handler
+
+      buffer = conn.line_buffer
+      buffer << data
+      while (index = buffer.index("\n"))
+        line = buffer.byteslice(0, index)
+        buffer = buffer.byteslice(index + 1..) || +"".b
+        line = line.chomp("\r")
+        begin
+          line_handler.call(conn, line)
+        rescue StandardError => e
+          Tina4::Log.error("tcp_service '#{@name}' on_line error: #{e.message}")
+        end
+      end
+      conn.line_buffer = buffer
+    end
+
+    def fire(event, conn)
+      handler = @callbacks[event]
+      return if handler.nil?
+
+      begin
+        handler.call(conn)
+      rescue StandardError => e
+        Tina4::Log.error("tcp_service '#{@name}' #{event} error: #{e.message}")
+      end
+    end
+
+    def peer_address(socket)
+      addr = socket.peeraddr(false)
+      "#{addr[3]}:#{addr[1]}"
+    rescue StandardError
+      ""
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  # Registry facade and the server-driven lifecycle hooks.
+  module Tcp
+    @services = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Register a named raw TCP service; the server binds it on boot (D1).
+      def service(port, **options, &block)
+        name = (options[:name] || "default").to_s
+        svc = TcpService.new(port, **options, &block)
+        @mutex.synchronize { @services[name] = svc }
+        svc
+      end
+
+      # The registry for a named service, for server -> device push. Raises for
+      # an unknown service name — a programming error, unlike a send to an
+      # unknown device id, which is a runtime no-op.
+      def get(name = "default")
+        svc = @mutex.synchronize { @services[name.to_s] }
+        return svc unless svc.nil?
+
+        known = @services.keys.empty? ? "(none registered)" : @services.keys.join(", ")
+        raise KeyError, "no tcp_service named '#{name}' is registered; known services: #{known}"
+      end
+
+      def registered
+        @mutex.synchronize { @services.values.dup }
+      end
+
+      # Drop every registered service (test isolation; not used in production).
+      def clear_registry
+        @mutex.synchronize { @services = {} }
+      end
+
+      # Start every registered service on boot (called by the web server).
+      def start_all(host = "0.0.0.0")
+        registered.each do |svc|
+          svc.start(host)
+        rescue StandardError => e
+          Tina4::Log.error("tcp_service '#{svc.name}' failed to start: #{e.message}")
+        end
+      end
+
+      # Stop every service accepting (shutdown step 1).
+      def stop_accepting_all
+        registered.each do |svc|
+          svc.stop_accepting
+        rescue StandardError => e
+          Tina4::Log.error("tcp_service '#{svc.name}' stop-accepting failed: #{e.message}")
+        end
+      end
+
+      # Drain and release every service's connections (shutdown drain step).
+      def drain_all(timeout: 5.0)
+        registered.each do |svc|
+          svc.drain(timeout: timeout)
+        rescue StandardError => e
+          Tina4::Log.error("tcp_service '#{svc.name}' drain failed: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/tina4/version.rb

@@ -7,5 +7,5 @@
 
 
 module Tina4
-  VERSION = "3.13.157"
+  VERSION = "3.13.158"
 end

data/lib/tina4/webserver.rb

@@ -130,6 +130,11 @@ module Tina4
       # rescue stays out of #start's cyclomatic complexity.
       bind_auxiliary_ai_port
 
+      # Raw TCP services (feature 142, ADR-0102 D1) run their acceptor threads in
+      # THIS process, beside the HTTP server — one process serves both the device
+      # gateway and its dashboard. Shutdown drains them (see Tina4::Shutdown).
+      Tina4::Tcp.start_all(@host)
+
       @server.start
 
       # Shutdown closes the listener FIRST, so #start returns as soon as the

data/lib/tina4.rb

@@ -48,6 +48,7 @@ require_relative "tina4/localization"
 require_relative "tina4/container"
 require_relative "tina4/service"
 require_relative "tina4/service_runner"
+require_relative "tina4/tcp"
 require_relative "tina4/events"
 require_relative "tina4/plan"
 require_relative "tina4/project_index"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.157
+  version: 3.13.158
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-11-02 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -354,6 +354,7 @@ files:
 - lib/tina4/sso.rb
 - lib/tina4/ssrf.rb
 - lib/tina4/swagger.rb
+- lib/tina4/tcp.rb
 - lib/tina4/template.rb
 - lib/tina4/templates/base.twig
 - lib/tina4/templates/crud/form.twig