Module: Tina4

Defined in:
lib/tina4/events.rb,
lib/tina4.rb,
lib/tina4/ai.rb,
lib/tina4/api.rb,
lib/tina4/cli.rb,
lib/tina4/env.rb,
lib/tina4/job.rb,
lib/tina4/log.rb,
lib/tina4/mcp.rb,
lib/tina4/orm.rb,
lib/tina4/auth.rb,
lib/tina4/cors.rb,
lib/tina4/crud.rb,
lib/tina4/docs.rb,
lib/tina4/plan.rb,
lib/tina4/wsdl.rb,
lib/tina4/cache.rb,
lib/tina4/debug.rb,
lib/tina4/frond.rb,
lib/tina4/queue.rb,
lib/tina4/health.rb,
lib/tina4/router.rb,
lib/tina4/seeder.rb,
lib/tina4/graphql.rb,
lib/tina4/metrics.rb,
lib/tina4/request.rb,
lib/tina4/session.rb,
lib/tina4/swagger.rb,
lib/tina4/testing.rb,
lib/tina4/version.rb,
lib/tina4/database.rb,
lib/tina4/rack_app.rb,
lib/tina4/response.rb,
lib/tina4/shutdown.rb,
lib/tina4/template.rb,
lib/tina4/auto_crud.rb,
lib/tina4/constants.rb,
lib/tina4/container.rb,
lib/tina4/dev_admin.rb,
lib/tina4/messenger.rb,
lib/tina4/migration.rb,
lib/tina4/validator.rb,
lib/tina4/webserver.rb,
lib/tina4/websocket.rb,
lib/tina4/background.rb,
lib/tina4/middleware.rb,
lib/tina4/dev_mailbox.rb,
lib/tina4/field_types.rb,
lib/tina4/test_client.rb,
lib/tina4/html_element.rb,
lib/tina4/localization.rb,
lib/tina4/rate_limiter.rb,
lib/tina4/error_overlay.rb,
lib/tina4/project_index.rb,
lib/tina4/query_builder.rb,
lib/tina4/scss_compiler.rb,
lib/tina4/response_cache.rb,
lib/tina4/service_runner.rb,
lib/tina4/database_result.rb,
lib/tina4/sql_translation.rb,
lib/tina4/drivers/odbc_driver.rb,
lib/tina4/websocket_backplane.rb,
lib/tina4/drivers/mssql_driver.rb,
lib/tina4/drivers/mysql_driver.rb,
lib/tina4/drivers/sqlite_driver.rb,
lib/tina4/drivers/mongodb_driver.rb,
lib/tina4/drivers/firebird_driver.rb,
lib/tina4/drivers/postgres_driver.rb,
lib/tina4/database/sqlite3_adapter.rb,
lib/tina4/queue_backends/lite_backend.rb,
lib/tina4/queue_backends/kafka_backend.rb,
lib/tina4/queue_backends/mongo_backend.rb,
lib/tina4/session_handlers/file_handler.rb,
lib/tina4/session_handlers/mongo_handler.rb,
lib/tina4/session_handlers/redis_handler.rb,
lib/tina4/queue_backends/rabbitmq_backend.rb,
lib/tina4/session_handlers/valkey_handler.rb,
lib/tina4/session_handlers/database_handler.rb

Overview

WebSocket Backplane Abstraction for Tina4 Ruby.

Enables broadcasting WebSocket messages across multiple server instances using a shared pub/sub channel (e.g. Redis). Without a backplane configured, broadcast() only reaches connections on the local process.

Configuration via environment variables:

TINA4_WS_BACKPLANE     — Backend type: "redis", "nats", or "" (default: none)
TINA4_WS_BACKPLANE_URL — Connection string (default: redis://localhost:6379)

Usage:

backplane = Tina4::WebSocketBackplane.create_backplane
if backplane
  backplane.subscribe("chat") { |msg| relay_to_local(msg) }
  backplane.publish("chat", '{"user":"A","text":"hello"}')
end

Defined Under Namespace

Modules: AI, Adapters, Auth, AutoCrud, Background, Container, CorsMiddleware, Crud, DevAdmin, Drivers, Env, ErrorOverlay, FieldTypes, Health, HtmlHelpers, Localization, Log, McpDevTools, McpProtocol, Metrics, Plan, ProjectIndex, QueueBackends, Router, ScssCompiler, SessionHandlers, Shutdown, Swagger, Template, Testing Classes: API, APIResponse, AiPortRackApp, CLI, ConnectionPool, CorsClassMiddleware, CsrfMiddleware, Database, DatabaseResult, DevMailbox, DevMessengerProxy, Docs, ErrorTracker, Events, FakeData, Frond, GraphQL, GraphQLError, GraphQLExecutor, GraphQLParser, GraphQLSchema, GraphQLType, HtmlElement, IndifferentHash, Job, LazySession, LegacyEnvError, McpServer, MessageLog, Messenger, Middleware, Migration, MigrationBase, NATSBackplane, ORM, QueryBuilder, QueryCache, Queue, RackApp, RateLimiter, RateLimiterMiddleware, RedisBackplane, Request, RequestInspector, RequestLoggerMiddleware, Response, ResponseCache, Route, SQLTranslator, SafeString, SecurityHeadersMiddleware, ServiceContext, ServiceRunner, Session, TestClient, TestResponse, Validator, WSDL, WebServer, WebSocket, WebSocketBackplane, WebSocketConnection, WebSocketRoute

Constant Summary collapse 

<<~'BANNER'

______ _             __ __
 /_  __/(_)___  ____ _/ // /
/ /  / / __ \/ __ `/ // /_
 / /  / / / / / /_/ /__  __/
/_/  /_/_/ /_/\__,_/  /_/
BANNER
LEGACY_ENV_VARS =

Legacy env var names that v3.12 has retired. If any of these are set in the environment we refuse to boot — silently ignoring them would cause auth/db/mail to fall back to defaults with no warning. Each maps to its new TINA4_-prefixed canonical name.

{
  "DATABASE_URL"           => "TINA4_DATABASE_URL",
  "DATABASE_USERNAME"      => "TINA4_DATABASE_USERNAME",
  "DATABASE_PASSWORD"      => "TINA4_DATABASE_PASSWORD",
  "DB_URL"                 => "TINA4_DATABASE_URL",
  "SECRET"                 => "TINA4_SECRET",
  "API_KEY"                => "TINA4_API_KEY",
  "JWT_ALGORITHM"          => "TINA4_JWT_ALGORITHM",
  "SMTP_HOST"              => "TINA4_MAIL_HOST",
  "SMTP_PORT"              => "TINA4_MAIL_PORT",
  "SMTP_USERNAME"          => "TINA4_MAIL_USERNAME",
  "SMTP_PASSWORD"          => "TINA4_MAIL_PASSWORD",
  "SMTP_FROM"              => "TINA4_MAIL_FROM",
  "SMTP_FROM_NAME"         => "TINA4_MAIL_FROM_NAME",
  "IMAP_HOST"              => "TINA4_MAIL_IMAP_HOST",
  "IMAP_PORT"              => "TINA4_MAIL_IMAP_PORT",
  "IMAP_USER"              => "TINA4_MAIL_IMAP_USERNAME",
  "IMAP_PASS"              => "TINA4_MAIL_IMAP_PASSWORD",
  "HOST_NAME"              => "TINA4_HOST_NAME",
  "SWAGGER_TITLE"          => "TINA4_SWAGGER_TITLE",
  "SWAGGER_DESCRIPTION"    => "TINA4_SWAGGER_DESCRIPTION",
  "SWAGGER_VERSION"        => "TINA4_SWAGGER_VERSION",
  "ORM_PLURAL_TABLE_NAMES" => "TINA4_ORM_PLURAL_TABLE_NAMES"
}.freeze
TYPE_MAP =

── Type mapping ──────────────────────────────────────────────────

{
  "String"    => "string",
  "Integer"   => "integer",
  "Float"     => "number",
  "Numeric"   => "number",
  "TrueClass" => "boolean",
  "FalseClass"=> "boolean",
  "Array"     => "array",
  "Hash"      => "object"
}.freeze
CRUD =

Uppercase alias for convenience: Tina4::CRUD.to_crud(…)

Crud
Debug = 
Log
VERSION = 
"3.12.5"
HTTP_OK =

── HTTP Status Codes ──

200
HTTP_CREATED = 
201
HTTP_ACCEPTED = 
202
HTTP_NO_CONTENT = 
204
HTTP_MOVED = 
301
HTTP_REDIRECT = 
302
HTTP_NOT_MODIFIED = 
304
HTTP_BAD_REQUEST = 
400
HTTP_UNAUTHORIZED = 
401
HTTP_FORBIDDEN = 
403
HTTP_NOT_FOUND = 
404
HTTP_METHOD_NOT_ALLOWED = 
405
HTTP_CONFLICT = 
409
HTTP_GONE = 
410
HTTP_UNPROCESSABLE = 
422
HTTP_TOO_MANY = 
429
HTTP_SERVER_ERROR = 
500
HTTP_BAD_GATEWAY = 
502
HTTP_UNAVAILABLE = 
503
APPLICATION_JSON =

── Content Types ──

"application/json"
APPLICATION_XML = 
"application/xml"
APPLICATION_FORM = 
"application/x-www-form-urlencoded"
APPLICATION_OCTET = 
"application/octet-stream"
TEXT_HTML = 
"text/html; charset=utf-8"
TEXT_PLAIN = 
"text/plain; charset=utf-8"
TEXT_CSV = 
"text/csv"
TEXT_XML = 
"text/xml"
HTTP_REASON_PHRASES =

── HTTP Reason Phrases (RFC 7231 / RFC 9110) ──

Used to write a correct HTTP/1.1 status line wherever the framework emits one manually. Previously code paths that built the status line by hand wrote “HTTP/1.1 404 OK” regardless of code, which is malformed. “Tina4.http_reason(status)“ always returns a non-empty phrase that matches the status family.

{
  100 => "Continue", 101 => "Switching Protocols",
  200 => "OK", 201 => "Created", 202 => "Accepted", 204 => "No Content",
  206 => "Partial Content",
  301 => "Moved Permanently", 302 => "Found", 303 => "See Other",
  304 => "Not Modified", 307 => "Temporary Redirect", 308 => "Permanent Redirect",
  400 => "Bad Request", 401 => "Unauthorized", 403 => "Forbidden",
  404 => "Not Found", 405 => "Method Not Allowed", 406 => "Not Acceptable",
  409 => "Conflict", 410 => "Gone", 413 => "Content Too Large",
  415 => "Unsupported Media Type", 422 => "Unprocessable Content",
  429 => "Too Many Requests",
  500 => "Internal Server Error", 501 => "Not Implemented",
  502 => "Bad Gateway", 503 => "Service Unavailable", 504 => "Gateway Timeout"
}.freeze
WEBSOCKET_GUID = 
"258EAFA5-E914-47DA-95CA-5AB5DC11AD37"

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.database ⇒ Object

Returns the value of attribute database.



119
120
121
 
# File 'lib/tina4.rb', line 119

def database
  @database
end

.root_dir ⇒ Object

Returns the value of attribute root_dir.



119
120
121
 
# File 'lib/tina4.rb', line 119

def root_dir
  @root_dir
end

Class Method Details

._default_mcp_server ⇒ Object 



425
426
427
 
# File 'lib/tina4/mcp.rb', line 425

def self._default_mcp_server
  @_default_mcp_server ||= McpServer.new("/__dev/mcp", name: "Tina4 Dev Tools")
end

.add_html_helpers(namespace) ⇒ Object

Inject _div(), _p(), _a(), etc. helper methods into the given namespace (hash or object).

Usage:

h = {}
Tina4.add_html_helpers(h)
h[:_div].call({ class: "card" }, h[:_p].call("Hello"))



156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/tina4/html_element.rb', line 156

def self.add_html_helpers(namespace)
  helper = Object.new.extend(HtmlHelpers)

  HtmlElement::HTML_TAGS.each do |tag|
    name = "_#{tag}"
    fn = helper.method(name.to_sym)

    if namespace.is_a?(Hash)
      namespace[name.to_sym] = fn
    else
      namespace.define_singleton_method(name.to_sym, &fn)
    end
  end
end

.after(pattern = nil, &block) ⇒ Object 



369
370
371
 
# File 'lib/tina4.rb', line 369

def after(pattern = nil, &block)
  Tina4::Middleware.after(pattern, &block)
end

.any(path, auth: false, swagger_meta: {}, &block) ⇒ Object 



317
318
319
320
321
322
 
# File 'lib/tina4.rb', line 317

def any(path, auth: false, swagger_meta: {}, &block)
  auth_handler = resolve_auth(auth)
  %w[GET POST PUT PATCH DELETE].each do |method|
    Tina4::Router.add(method, path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
  end
end

.background(callback = nil, interval: 1.0, &block) ⇒ Object

Register a periodic background task. Mirrors Python’s tina4_python.core.server.background(fn, interval) and PHP’s $app->background($callback, $interval).

Tina4.background(interval: 5.0) { drain_queue }
Tina4.background(method(:health_check), interval: 30.0)



399
400
401
 
# File 'lib/tina4.rb', line 399

def background(callback = nil, interval: 1.0, &block)
  Tina4::Background.register(callback, interval: interval, &block)
end

.before(pattern = nil, &block) ⇒ Object

Middleware hooks



365
366
367
 
# File 'lib/tina4.rb', line 365

def before(pattern = nil, &block)
  Tina4::Middleware.before(pattern, &block)
end

.build_frame(opcode, data, fin: true) ⇒ Object

Build a WebSocket frame (server→client, never masked).



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/tina4/websocket.rb', line 17

def self.build_frame(opcode, data, fin: true)
  first_byte = (fin ? 0x80 : 0x00) | opcode
  frame = [first_byte].pack("C")
  length = data.bytesize

  if length < 126
    frame += [length].pack("C")
  elsif length < 65536
    frame += [126, length].pack("Cn")
  else
    frame += [127, length].pack("CQ>")
  end

  frame + data
end

.cache_clear ⇒ Object

Backward-compat alias for cache_clear (deprecated — use clear_cache).



625
626
627
 
# File 'lib/tina4/response_cache.rb', line 625

def cache_clear
  cache_instance.clear_cache
end

.cache_delete(key) ⇒ Object 



610
611
612
 
# File 'lib/tina4/response_cache.rb', line 610

def cache_delete(key)
  cache_instance.cache_delete(key)
end

.cache_get(key) ⇒ Object

Module-level KV API (parity with Python tina4_python.cache).



602
603
604
 
# File 'lib/tina4/response_cache.rb', line 602

def cache_get(key)
  cache_instance.cache_get(key)
end

.cache_instance ⇒ Object

Lazy module-level singleton for cache_stats / clear_cache.



597
598
599
 
# File 'lib/tina4/response_cache.rb', line 597

def cache_instance
  @default_cache ||= ResponseCache.new(ttl: ENV["TINA4_CACHE_TTL"] ? ENV["TINA4_CACHE_TTL"].to_i : 60)
end

.cache_set(key, value, ttl: 0) ⇒ Object 



606
607
608
 
# File 'lib/tina4/response_cache.rb', line 606

def cache_set(key, value, ttl: 0)
  cache_instance.cache_set(key, value, ttl: ttl)
end

.cache_stats ⇒ Object

Module-level cache stats (parity with Python tina4_python.cache.cache_stats()).



615
616
617
 
# File 'lib/tina4/response_cache.rb', line 615

def cache_stats
  cache_instance.cache_stats
end

.camel_to_snake(name) ⇒ Object

Convert a camelCase name to snake_case.



12
13
14
 
# File 'lib/tina4/orm.rb', line 12

def self.camel_to_snake(name)
  name.to_s.gsub(/([A-Z])/) { "_#{$1.downcase}" }.sub(/^_/, "")
end

.check_legacy_env_vars!(io: $stderr, exit_on_error: true) ⇒ Object

Refuse to boot if pre-3.12 un-prefixed env vars are still set.

Tina4 v3.12 hard-renamed every framework-specific env var to use the TINA4_ prefix. Booting silently with a legacy DATABASE_URL or SECRET would let auth, DB, or mail fall back to insecure defaults while the user thought their config was being read. Better to die loudly with a list of names to fix.

Bypass with TINA4_ALLOW_LEGACY_ENV=true in CI / migration scripts that genuinely need both names set during a transition window.

Raises:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/tina4/env.rb', line 47

def self.check_legacy_env_vars!(io: $stderr, exit_on_error: true)
  bypass = ENV["TINA4_ALLOW_LEGACY_ENV"].to_s.downcase
  return if %w[true 1 yes].include?(bypass)

  found = LEGACY_ENV_VARS.keys.select { |name| ENV.key?(name) }.sort
  return if found.empty?

  sep = "─" * 72
  lines = ["", sep,
           "Tina4 v3.12 requires TINA4_ prefix on all framework env vars.",
           "Your environment still has these legacy names:",
           ""]
  found.each do |old|
    new_name = LEGACY_ENV_VARS[old]
    lines << format("    %-28s  →  %s", old, new_name)
  end
  lines.concat([
                 "",
                 "Run `tina4 env --migrate` to rewrite your .env automatically,",
                 "or rename manually. See https://tina4.com/release/3.12.0",
                 "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                 sep, ""
               ])
  io.puts lines.join("\n")
  raise LegacyEnvError, "Legacy env vars present: #{found.join(', ')}" unless exit_on_error

  exit(2)
end

.clear_cache ⇒ Object

Module-level cache clear (parity with Python tina4_python.cache.clear_cache()).



620
621
622
 
# File 'lib/tina4/response_cache.rb', line 620

def clear_cache
  cache_instance.clear_cache
end

.compute_accept_key(key) ⇒ Object

Compute Sec-WebSocket-Accept from Sec-WebSocket-Key per RFC 6455.



12
13
14
 
# File 'lib/tina4/websocket.rb', line 12

def self.compute_accept_key(key)
  Base64.strict_encode64(Digest::SHA1.digest("#{key}#{WEBSOCKET_GUID}"))
end

.create_messenger(**options) ⇒ Object

Factory: returns a DevMailbox-intercepting messenger in dev mode, or a real Messenger in production.



549
550
551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/tina4/messenger.rb', line 549

def self.create_messenger(**options)
  dev_mode = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])

  smtp_configured = ENV["TINA4_MAIL_HOST"] && !ENV["TINA4_MAIL_HOST"].empty?

  if dev_mode && !smtp_configured
    mailbox_dir = options.delete(:mailbox_dir) || ENV["TINA4_MAILBOX_DIR"]
    mailbox = DevMailbox.new(mailbox_dir: mailbox_dir)
    DevMessengerProxy.new(mailbox, **options)
  else
    Messenger.new(**options)
  end
end

.delete(path, auth: :default, swagger_meta: {}, &block) ⇒ Object 



312
313
314
315
 
# File 'lib/tina4.rb', line 312

def delete(path, auth: :default, swagger_meta: {}, &block)
  auth_handler = resolve_auth(auth)
  Tina4::Router.add("DELETE", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.describe(name, &block) ⇒ Object

Inline test DSL



379
380
381
 
# File 'lib/tina4.rb', line 379

def describe(name, &block)
  Tina4::Testing.describe(name, &block)
end

.find_available_port(start, max_tries = 10) ⇒ Object

Initialize and start the web server. This is the primary entry point for app.rb files:

Tina4.initialize!(__dir__)
Tina4.run!

Or combined: Tina4.run!(__dir__)



196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/tina4.rb', line 196

def find_available_port(start, max_tries = 10)
  require "socket"
  max_tries.times do |offset|
    port = start + offset
    begin
      server = TCPServer.new("127.0.0.1", port)
      server.close
      return port
    rescue Errno::EADDRINUSE, Errno::EACCES
      next
    end
  end
  start
end

.get(path, auth: nil, swagger_meta: {}, &block) ⇒ Object

DSL methods for route registration GET is public by default (matching tina4_python behavior) POST/PUT/PATCH/DELETE are secured by default — use auth: false to make public



292
293
294
295
 
# File 'lib/tina4.rb', line 292

def get(path, auth: nil, swagger_meta: {}, &block)
  auth_handler = auth == false ? nil : auth
  Tina4::Router.add("GET", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.get_framework_frond ⇒ Object

Return the singleton Frond engine for built-in framework templates.



18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/tina4/response.rb', line 18

def self.get_framework_frond
  framework_dir = ::File.join(::File.dirname(__FILE__), "templates")
  if @_framework_frond.nil? && ::File.directory?(framework_dir)
    @_framework_frond = Tina4::Frond.new(template_dir: framework_dir)
  end
  # Sync custom filters/globals from the user engine
  if @_framework_frond
    user_engine = get_frond
    @_framework_frond.instance_variable_get(:@filters).merge!(user_engine.instance_variable_get(:@filters))
    @_framework_frond.instance_variable_get(:@globals).merge!(user_engine.instance_variable_get(:@globals))
  end
  @_framework_frond
end

.get_frond ⇒ Object

Return the global Frond engine, creating a default if needed.



13
14
15
 
# File 'lib/tina4/response.rb', line 13

def self.get_frond
  @_global_frond ||= Tina4::Frond.new(template_dir: "src/templates")
end

.group(prefix, auth: nil, &block) ⇒ Object

Route groups



355
356
357
 
# File 'lib/tina4.rb', line 355

def group(prefix, auth: nil, &block)
  Tina4::Router.group(prefix, auth_handler: auth, &block)
end

.html_helpers ⇒ Object

Module-level convenience: Tina4.html_helpers returns a module you can include.



145
146
147
 
# File 'lib/tina4/html_element.rb', line 145

def self.html_helpers
  HtmlHelpers
end

.http_reason(status) ⇒ Object

Return the canonical HTTP reason phrase for “status“.

Falls back to a sensible label when an exotic status is used. Never returns an empty string — the HTTP/1.1 status line requires a phrase. Prefers Rack::Utils::HTTP_STATUS_CODES when Rack is available so the phrase tracks Rack’s mapping, otherwise uses the local table above.



75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/tina4/constants.rb', line 75

def self.http_reason(status)
  code = status.to_i
  if defined?(Rack::Utils::HTTP_STATUS_CODES)
    phrase = Rack::Utils::HTTP_STATUS_CODES[code]
    return phrase if phrase && !phrase.empty?
  end
  phrase = HTTP_REASON_PHRASES[code]
  return phrase if phrase && !phrase.empty?
  return "OK" if code >= 200 && code < 300
  "Error"
end

.initialize!(root_dir = Dir.pwd) ⇒ Object 



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/tina4.rb', line 160

def initialize!(root_dir = Dir.pwd)
  @root_dir = root_dir

  # Print banner
  print_banner

  # Load environment
  Tina4::Env.load_env(root_dir)

  # Setup debug logging
  Tina4::Log.configure(root_dir)
  Tina4::Log.info("Tina4 Ruby v#{VERSION} initializing...")

  # Setup auth keys
  Tina4::Auth.setup(root_dir)

  # Load translations
  Tina4::Localization.load(root_dir)

  # Auto-wire t() into template globals if locales were loaded
  autowire_i18n_template_global

  # Connect database if configured
  setup_database

  # Auto-discover routes
  auto_discover(root_dir)

  Tina4::Log.info("Tina4 initialized successfully")
end

.is_localhost? ⇒ Boolean

Check if the server is running on localhost.

Returns:

  • (Boolean) 


134
135
136
137
 
# File 'lib/tina4/mcp.rb', line 134

def self.is_localhost?
  host = ENV.fetch("TINA4_HOST_NAME", "localhost:7145").split(":").first
  ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].include?(host)
end

.mcp_enabled? ⇒ Boolean

Resolve whether the built-in MCP dev server should be active.

Precedence:

* TINA4_MCP set explicitly → use that (truthy/falsey).
* Otherwise: enabled only when TINA4_DEBUG=true.

Returns:

  • (Boolean) 


144
145
146
147
148
149
150
 
# File 'lib/tina4/mcp.rb', line 144

def self.mcp_enabled?
  explicit = ENV["TINA4_MCP"]
  if explicit && !explicit.empty?
    return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
  end
  %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
end

.mcp_port ⇒ Object

Resolve the dedicated MCP port. Defaults to (server port + 2000) — keeps MCP tooling reachable on a stable, predictable channel separate from the main HTTP port and the AI test port (port + 1000).



155
156
157
158
159
160
161
 
# File 'lib/tina4/mcp.rb', line 155

def self.mcp_port
  explicit = ENV["TINA4_MCP_PORT"]
  return explicit.to_i if explicit && !explicit.empty? && explicit.to_i > 0

  base_port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i
  base_port + 2000
end

.mcp_resource(uri, description: "", mime_type: "application/json", server: nil, &block) ⇒ Object

Register a block as an MCP resource.

Tina4.mcp_resource("app://tables", description: "Database tables") do
  db.tables
end



447
448
449
450
451
 
# File 'lib/tina4/mcp.rb', line 447

def self.mcp_resource(uri, description: "", mime_type: "application/json", server: nil, &block)
  target = server || _default_mcp_server
  target.register_resource(uri, block, description, mime_type)
  block
end

.mcp_tool(name, description: "", server: nil, &block) ⇒ Object

Register a block as an MCP tool.

Tina4.mcp_tool("lookup_invoice", description: "Find invoice by number") do |invoice_no:|
  db.fetch_one("SELECT * FROM invoices WHERE invoice_no = ?", [invoice_no])
end



434
435
436
437
438
439
440
 
# File 'lib/tina4/mcp.rb', line 434

def self.mcp_tool(name, description: "", server: nil, &block)
  target = server || _default_mcp_server
  handler = block
  tool_desc = description.empty? ? name : description
  target.register_tool(name, handler, tool_desc)
  handler
end

.open_browser(url) ⇒ Object 



211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/tina4.rb', line 211

def open_browser(url)
  require "rbconfig"
  Thread.new do
    sleep 2
    case RbConfig::CONFIG["host_os"]
    when /darwin/i then system("open", url)
    when /mswin|mingw/i then system("start", url)
    else system("xdg-open", url)
    end
  end
end

.options(path, &block) ⇒ Object 



324
325
326
 
# File 'lib/tina4.rb', line 324

def options(path, &block)
  Tina4::Router.add("OPTIONS", path, block)
end

.patch(path, auth: :default, swagger_meta: {}, &block) ⇒ Object 



307
308
309
310
 
# File 'lib/tina4.rb', line 307

def patch(path, auth: :default, swagger_meta: {}, &block)
  auth_handler = resolve_auth(auth)
  Tina4::Router.add("PATCH", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.post(path, auth: :default, swagger_meta: {}, &block) ⇒ Object 



297
298
299
300
 
# File 'lib/tina4.rb', line 297

def post(path, auth: :default, swagger_meta: {}, &block)
  auth_handler = resolve_auth(auth)
  Tina4::Router.add("POST", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.print_banner(host: "0.0.0.0", port: 7147, server_name: nil) ⇒ Object 



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/tina4.rb', line 121

def print_banner(host: "0.0.0.0", port: 7147, server_name: nil)
  # TINA4_SUPPRESS — short-circuit ALL banner output for headless / CI runs.
  return if Tina4::Env.is_truthy(ENV["TINA4_SUPPRESS"])

  is_tty = $stdout.respond_to?(:isatty) && $stdout.isatty
  color = is_tty ? "\e[31m" : ""
  reset = is_tty ? "\e[0m" : ""

  is_debug = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
  log_level = (ENV["TINA4_LOG_LEVEL"] || "[TINA4_LOG_ALL]").upcase
  display = (host == "0.0.0.0" || host == "::") ? "localhost" : host

  # Auto-detect server name if not provided
  if server_name.nil?
    if is_debug
      server_name = "WEBrick"
    else
      begin
        require "puma"
        server_name = "puma"
      rescue LoadError
        server_name = "WEBrick"
      end
    end
  end

  puts "#{color}#{BANNER}#{reset}"
  puts "  TINA4 — The Intelligent Native Application 4ramework"
  puts "  Simple. Fast. Human. | Built for AI. Built for you."
  puts ""
  puts "  Server:    http://#{display}:#{port} (#{server_name})"
  puts "  Swagger:   http://localhost:#{port}/swagger"
  puts "  Dashboard: http://localhost:#{port}/__dev"
  puts "  Debug:     #{is_debug ? 'ON' : 'OFF'} (Log level: #{log_level})"
  puts ""
rescue
  puts "#{color}TINA4 Ruby v#{VERSION}#{reset}"
end

.put(path, auth: :default, swagger_meta: {}, &block) ⇒ Object 



302
303
304
305
 
# File 'lib/tina4.rb', line 302

def put(path, auth: :default, swagger_meta: {}, &block)
  auth_handler = resolve_auth(auth)
  Tina4::Router.add("PUT", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.register(name, instance = nil, &block) ⇒ Object

DI container shortcuts



404
405
406
 
# File 'lib/tina4.rb', line 404

def register(name, instance = nil, &block)
  Tina4::Container.register(name, instance, &block)
end

.resolve(name) ⇒ Object 



412
413
414
 
# File 'lib/tina4.rb', line 412

def resolve(name)
  Tina4::Container.get(name)
end

.run!(root_dir = nil, port: nil, host: nil, debug: nil) ⇒ Object 



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/tina4.rb', line 223

def run!(root_dir = nil, port: nil, host: nil, debug: nil)
  # Handle legacy call: run!(port: 7147) where root_dir receives the hash
  if root_dir.is_a?(Hash)
    port ||= root_dir[:port]
    host ||= root_dir[:host]
    debug = root_dir[:debug] if debug.nil? && root_dir.key?(:debug)
    root_dir = nil
  end
  root_dir ||= Dir.pwd

  ENV["PORT"] = port.to_s if port
  ENV["HOST"] = host.to_s if host
  ENV["TINA4_DEBUG"] = debug.to_s unless debug.nil?

  initialize!(root_dir) unless @root_dir

  host = ENV.fetch("HOST", ENV.fetch("TINA4_HOST", "0.0.0.0"))
  port = ENV.fetch("PORT", ENV.fetch("TINA4_PORT", "7147")).to_i

  actual_port = find_available_port(port)
  if actual_port != port
    Tina4::Log.info("Port #{port} in use, using #{actual_port}")
    port = actual_port
  end

  display_host = (host == "0.0.0.0" || host == "::") ? "localhost" : host
  url = "http://#{display_host}:#{port}"

  app = Tina4::RackApp.new(root_dir: root_dir)
  is_debug = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])

  # Try Puma first (production-grade), fall back to WEBrick
  if !is_debug
    begin
      require "puma"
      require "puma/configuration"
      require "puma/launcher"

      config = Puma::Configuration.new do |user_config|
        user_config.bind "tcp://#{host}:#{port}"
        user_config.app app
        user_config.threads 0, 16
        user_config.workers 0
        user_config.environment "production"
        user_config.log_requests false
        user_config.quiet
      end

      Tina4::Log.info("Production server: puma")
      Tina4::Shutdown.setup

      open_browser(url)
      launcher = Puma::Launcher.new(config)
      launcher.run
      return
    rescue LoadError
      # Puma not installed, fall through to WEBrick
    end
  end

  Tina4::Log.info("Development server: WEBrick")
  open_browser(url)
  server = Tina4::WebServer.new(app, host: host, port: port)
  server.start
end

.run_seeds(seed_folder: "seeds", clear: false) ⇒ Object

Run all seed files in the given folder.

Parity: Python/PHP/Node use ‘seed(n)` to set the PRNG seed on FakeData. Ruby’s FakeData.seed already does that — this folder-runner is named differently to avoid the collision.

Parameters:

  • seed_folder (String) (defaults to: "seeds") —

    path to seed files (default: “seeds”)



534
535
536
 
# File 'lib/tina4/seeder.rb', line 534

def self.run_seeds(seed_folder: "seeds", clear: false)
  seed_dir(seed_folder: seed_folder, clear: clear)
end

.schema_from_method(method_obj) ⇒ Object

Extract JSON Schema input schema from a Ruby method’s parameters.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/tina4/mcp.rb', line 106

def self.schema_from_method(method_obj)
  properties = {}
  required   = []

  method_obj.parameters.each do |kind, name|
    next if name == :self
    name_s = name.to_s

    # Default type is "string" -- Ruby doesn't have inline type annotations
    prop = { "type" => "string" }

    case kind
    when :req, :keyreq
      required << name_s
    when :opt, :key
      # Has a default -- we cannot inspect the default value easily in Ruby,
      # so we just mark it as optional (no "default" key)
    end

    properties[name_s] = prop
  end

  schema = { "type" => "object", "properties" => properties }
  schema["required"] = required unless required.empty?
  schema
end

.secure_delete(path, auth: nil, swagger_meta: {}, &block) ⇒ Object 



349
350
351
352
 
# File 'lib/tina4.rb', line 349

def secure_delete(path, auth: nil, swagger_meta: {}, &block)
  auth_handler = auth || Tina4::Auth.default_secure_auth
  Tina4::Router.add("DELETE", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.secure_get(path, auth: nil, swagger_meta: {}, &block) ⇒ Object

Explicit secure variants (always secured, regardless of HTTP method)



329
330
331
332
 
# File 'lib/tina4.rb', line 329

def secure_get(path, auth: nil, swagger_meta: {}, &block)
  auth_handler = auth || Tina4::Auth.default_secure_auth
  Tina4::Router.add("GET", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.secure_patch(path, auth: nil, swagger_meta: {}, &block) ⇒ Object 



344
345
346
347
 
# File 'lib/tina4.rb', line 344

def secure_patch(path, auth: nil, swagger_meta: {}, &block)
  auth_handler = auth || Tina4::Auth.default_secure_auth
  Tina4::Router.add("PATCH", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.secure_post(path, auth: nil, swagger_meta: {}, &block) ⇒ Object 



334
335
336
337
 
# File 'lib/tina4.rb', line 334

def secure_post(path, auth: nil, swagger_meta: {}, &block)
  auth_handler = auth || Tina4::Auth.default_secure_auth
  Tina4::Router.add("POST", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.secure_put(path, auth: nil, swagger_meta: {}, &block) ⇒ Object 



339
340
341
342
 
# File 'lib/tina4.rb', line 339

def secure_put(path, auth: nil, swagger_meta: {}, &block)
  auth_handler = auth || Tina4::Auth.default_secure_auth
  Tina4::Router.add("PUT", path, block, auth_handler: auth_handler, swagger_meta: swagger_meta)
end

.seed_batch(tasks, clear: false) ⇒ Hash

Seed multiple ORM classes in batch with optional dependency-aware clearing.

Examples:

Tina4.seed_batch([
  { orm_class: User, count: 20 },
  { orm_class: Order, count: 100, overrides: { status: "pending" } }
], clear: true)

Parameters:

  • tasks (Array<Hash>) —

    each hash has :orm_class, :count, :overrides, :seed

  • clear (Boolean) (defaults to: false) —

    delete existing records (in reverse order) before seeding

Returns:

  • (Hash) —

    { “ClassName” => inserted_count, … }



499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/tina4/seeder.rb', line 499

def self.seed_batch(tasks, clear: false)
  results = {}

  if clear
    tasks.reverse_each do |task|
      begin
        Tina4.database&.execute("DELETE FROM #{task[:orm_class].table_name}")
        Tina4::Log.info("Seeder: Cleared #{task[:orm_class].table_name}")
      rescue => e
        Tina4::Log.warn("Seeder: Could not clear #{task[:orm_class].table_name}: #{e.message}")
      end
    end
  end

  tasks.each do |task|
    n = Tina4.seed_orm(
      task[:orm_class],
      count: task[:count] || 10,
      overrides: task[:overrides] || {},
      clear: false,
      seed: task[:seed]
    )
    results[task[:orm_class].name] = n
  end

  results
end

.seed_dir(seed_folder: "seeds", clear: false) ⇒ Object

Run all seed files in the given folder.

Parameters:

  • seed_folder (String) (defaults to: "seeds") —

    path to seed files (default: “seeds”)



541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
 
# File 'lib/tina4/seeder.rb', line 541

def self.seed_dir(seed_folder: "seeds", clear: false)
  unless Dir.exist?(seed_folder)
    Tina4::Log.info("Seeder: No seeds folder found at #{seed_folder}")
    return
  end

  files = Dir.glob(File.join(seed_folder, "*.rb")).sort
  files.reject! { |f| File.basename(f).start_with?("_") }

  if files.empty?
    Tina4::Log.info("Seeder: No seed files found in #{seed_folder}")
    return
  end

  Tina4::Log.info("Seeder: Found #{files.length} seed file(s) in #{seed_folder}")

  files.each do |filepath|
    begin
      Tina4::Log.info("Seeder: Running #{File.basename(filepath)}...")
      load filepath
      Tina4::Log.info("Seeder: Completed #{File.basename(filepath)}")
    rescue => e
      Tina4::Log.error("Seeder: Failed to run #{File.basename(filepath)}: #{e.message}")
    end
  end
end

.seed_orm(orm_class, count: 10, overrides: {}, clear: false, seed: nil) ⇒ Integer

Seed an ORM class with auto-generated fake data.

Examples:

Tina4.seed_orm(User, count: 50)
Tina4.seed_orm(Order, count: 200, overrides: { status: ->(f) { f.choice(%w[pending shipped]) } })

Parameters:

  • orm_class (Class) —

    ORM subclass (e.g., User, Product)

  • count (Integer) (defaults to: 10) —

    number of records to insert

  • overrides (Hash) (defaults to: {}) —

    field overrides — static values or lambdas receiving FakeData

  • clear (Boolean) (defaults to: false) —

    delete existing records before seeding

  • seed (Integer, nil) (defaults to: nil) —

    random seed for reproducible data

Returns:

  • (Integer) —

    number of records inserted



364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/tina4/seeder.rb', line 364

def self.seed_orm(orm_class, count: 10, overrides: {}, clear: false, seed: nil)
  fake = FakeData.new(seed: seed)
  fields = orm_class.field_definitions
  table = orm_class.table_name

  if fields.empty?
    Tina4::Log.error("Seeder: No fields found on #{orm_class.name}")
    return 0
  end

  db = Tina4.database
  unless db
    Tina4::Log.error("Seeder: No database connection. Set Tina4.database first.")
    return 0
  end

  # Idempotency check
  unless clear
    begin
      result = db.fetch_one("SELECT count(*) as cnt FROM #{table}")
      if result && result[:cnt].to_i >= count
        Tina4::Log.info("Seeder: #{table} already has #{result[:cnt]} records, skipping")
        return 0
      end
    rescue => e
      # Table might not exist
    end
  end

  # Clear if requested
  if clear
    begin
      db.execute("DELETE FROM #{table}")
      Tina4::Log.info("Seeder: Cleared #{table}")
    rescue => e
      Tina4::Log.warn("Seeder: Could not clear #{table}: #{e.message}")
    end
  end

  # Identify fields to populate
  pk_field = orm_class.primary_key_field
  insert_fields = fields.reject { |name, opts| opts[:primary_key] && opts[:auto_increment] }

  inserted = 0
  count.times do |i|
    attrs = {}

    insert_fields.each do |name, field_def|
      if overrides.key?(name)
        val = overrides[name]
        attrs[name] = val.respond_to?(:call) ? val.call(fake) : val
      else
        generated = fake.for_field(field_def, name)
        attrs[name] = generated unless generated.nil?
      end
    end

    begin
      obj = orm_class.new(attrs)
      if obj.save
        inserted += 1
      else
        Tina4::Log.warn("Seeder: Insert failed for #{table} row #{i + 1}: #{obj.errors.join(', ')}")
      end
    rescue => e
      Tina4::Log.warn("Seeder: Insert failed for #{table} row #{i + 1}: #{e.message}")
    end
  end

  Tina4::Log.info("Seeder: Inserted #{inserted}/#{count} records into #{table}")
  inserted
end

.seed_table(table_name, columns, count: 10, overrides: {}, clear: false, seed: nil) ⇒ Integer

Seed a raw database table (no ORM class needed).

Parameters:

  • table_name (String) —

    name of the table

  • columns (Hash) —

    { column_name: type_string } — supports :integer, :string, :text, etc.

  • count (Integer) (defaults to: 10) —

    number of records to insert

  • overrides (Hash) (defaults to: {}) —

    field overrides

  • clear (Boolean) (defaults to: false) —

    delete before seeding

  • seed (Integer, nil) (defaults to: nil) —

    random seed

Returns:

  • (Integer) —

    records inserted



446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
 
# File 'lib/tina4/seeder.rb', line 446

def self.seed_table(table_name, columns, count: 10, overrides: {}, clear: false, seed: nil)
  fake = FakeData.new(seed: seed)
  db = Tina4.database

  unless db
    Tina4::Log.error("Seeder: No database connection.")
    return 0
  end

  if clear
    begin
      db.execute("DELETE FROM #{table_name}")
    rescue => e
      Tina4::Log.warn("Seeder: Could not clear #{table_name}: #{e.message}")
    end
  end

  inserted = 0
  count.times do |i|
    row = {}
    columns.each do |col_name, type_str|
      if overrides.key?(col_name)
        val = overrides[col_name]
        row[col_name] = val.respond_to?(:call) ? val.call(fake) : val
      else
        field_def = { type: type_str.to_sym }
        row[col_name] = fake.for_field(field_def, col_name)
      end
    end

    begin
      db.insert(table_name, row)
      inserted += 1
    rescue => e
      Tina4::Log.warn("Seeder: Insert failed for #{table_name} row #{i + 1}: #{e.message}")
    end
  end

  Tina4::Log.info("Seeder: Inserted #{inserted}/#{count} records into #{table_name}")
  inserted
end

.service(name, options = {}, &block) ⇒ Object

Service runner DSL



389
390
391
 
# File 'lib/tina4.rb', line 389

def service(name, options = {}, &block)
  Tina4::ServiceRunner.register(name, nil, options, &block)
end

.set_frond(engine) ⇒ Object

Register a pre-configured Frond engine for response.render().



33
34
35
 
# File 'lib/tina4/response.rb', line 33

def self.set_frond(engine)
  @_global_frond = engine
end

.singleton(name, &block) ⇒ Object 



408
409
410
 
# File 'lib/tina4.rb', line 408

def singleton(name, &block)
  Tina4::Container.singleton(name, &block)
end

.snake_to_camel(name) ⇒ Object

Convert a snake_case name to camelCase.



6
7
8
9
 
# File 'lib/tina4/orm.rb', line 6

def self.snake_to_camel(name)
  parts = name.to_s.split("_")
  parts[0] + parts[1..].map(&:capitalize).join
end

.t(key, **options) ⇒ Object

Translation shortcut



384
385
386
 
# File 'lib/tina4.rb', line 384

def t(key, **options)
  Tina4::Localization.t(key, **options)
end

.template_global(key, value) ⇒ Object

Template globals



374
375
376
 
# File 'lib/tina4.rb', line 374

def template_global(key, value)
  Tina4::Template.add_global(key, value)
end

.websocket(path, &block) ⇒ Object

WebSocket route registration



360
361
362
 
# File 'lib/tina4.rb', line 360

def websocket(path, &block)
  Tina4::Router.websocket(path, &block)
end