hamster-web 0.1.0.pre.2

data/lib/hamster/web/view.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Hamster
+  module View
+    class Error < StandardError; end
+
+    def self.configure(site_name:, routes:)
+      @site_name = site_name
+      @routes = routes
+    end
+
+    def self.route_mapping
+      @routes
+    end
+
+    class Context
+      def initialize(name = nil, locals = nil)
+        @name = name
+        @locals = locals
+        @slots = {}
+      end
+
+      def fetch(*args)
+        locals, template, name, line = if args.length == 2
+                                         [@locals, @name, args[0], args[1]]
+                                       else
+                                         args
+                                       end
+        key = name.to_sym
+        return locals[key] if locals.key?(key)
+        return locals[name] if locals.key?(name)
+
+        raise Error, "#{template}:#{line}: missing local #{name}"
+      end
+
+      def content_for(name, fragment)
+        key = name.to_s
+        @slots[key] = HTML.join([@slots[key], fragment])
+        nil
+      end
+
+      def slot(name)
+        @slots[name.to_s] || HTML::Fragment.new("")
+      end
+    end
+
+    URL_ATTRIBUTES = %w[href src action formaction].freeze
+    TOKEN = /<%=(.*?)%>/m
+    NAME = /\A[a-z][a-z0-9_]*(?:\/[a-z][a-z0-9_]*)*\z/
+    LOCAL = /\A[a-z][a-z0-9_]*\z/
+
+    module_function
+
+    def render_compiled(name, locals = {}, layout: "layouts/application")
+      context = Context.new
+      body = CompiledViews.render(name, context, locals)
+      return body if layout.nil?
+
+      context.content_for("body", body)
+      title = context.slot("title")
+      site_name = @site_name || "Hamster"
+      full_title = title.to_s.empty? ? site_name : HTML.join([title, " · ", site_name])
+      CompiledViews.render(layout, context, title: full_title)
+    end
+
+    def append_value(output, value, name, line, position)
+      validate_url!(value, name, line) if URL_ATTRIBUTES.include?(position)
+      value = HTML.escape(value.to_s) if position.is_a?(String) && value.instance_of?(HTML::Fragment)
+      output << HTML.escape(value).to_s
+    end
+
+    def instrument_compiled(name)
+      kind = name.start_with?("layouts/") ? "layout" : name.include?("/shared/") ? "partial" : "template"
+      Hamster::Instrumentation.instrument("view.render", attributes: {"view.template" => name, "view.kind" => kind}) { yield }
+    end
+
+    def prepare!(sources)
+      @templates = compile(sources)
+    end
+
+    def use_compiled!
+      @templates = nil
+    end
+
+    def validate!(sources)
+      compile(sources)
+      true
+    end
+
+    def compile(sources)
+      prepared = {}
+      sources.each do |name, source|
+        raise Error, "invalid template name #{name}" unless name.match?(NAME)
+        instructions = []
+        cursor = 0
+        source.to_enum(:scan, TOKEN).each do
+          match = Regexp.last_match
+          prefix = source[0...match.begin(0)]
+          literal = source[cursor...match.begin(0)]
+          instructions << [:literal, literal.freeze] unless literal.empty?
+          line = prefix.count("\n") + 1
+          location = "#{name}:#{line}"
+          context = position(prefix.gsub(TOKEN, ""))
+          expression = match[1].strip
+          unless expression.match?(LOCAL)
+            raise Error, "#{location}: only <%= local %> is supported; compose partials in Ruby (got #{expression})"
+          end
+          raise Error, "#{location}: dynamic script or style content" if context == :script
+          raise Error, "#{location}: substitution must be in text or a quoted attribute" if context == :tag
+          if context.is_a?(String)
+            raise Error, "#{location}: dynamic event or style attribute" if context.start_with?("on") || context == "style" || context == "srcdoc"
+          end
+          instructions << [:value, expression.freeze, context, line].freeze
+          cursor = match.end(0)
+        end
+        tail = source[cursor..-1]
+        instructions << [:literal, tail.freeze] unless tail.empty?
+        unsupported = source.index(/<%(?!\=)/)
+        if unsupported
+          invalid_line = source[0...unsupported].count("\n") + 1
+          raise Error, "#{name}:#{invalid_line}: unsupported ERB tag; only <%= local %> is supported"
+        end
+        if tail.include?("<%")
+          invalid_line = source[0...cursor].count("\n") + tail[0...tail.index("<%")].count("\n") + 1
+          raise Error, "#{name}:#{invalid_line}: unterminated or unsupported ERB tag"
+        end
+        prepared[name.freeze] = instructions.freeze
+      end
+      prepared.freeze
+    end
+
+    def position(prefix)
+      script_tag = prefix.scan(%r{</?(?:script|style)\b[^>]*>}i).last
+      return :script if script_tag && !script_tag.start_with?("</")
+
+      open = prefix.rindex("<")
+      close = prefix.rindex(">")
+      if open && (!close || open > close)
+        tag = prefix[open..-1]
+        match = tag.match(/([a-zA-Z][a-zA-Z0-9:-]*)\s*=\s*(["'])[^"']*\z/)
+        return match[1].downcase if match
+        return :tag
+      end
+      :text
+    end
+
+    def render(name, locals = {}, kind = nil, **options)
+      if RUBY_ENGINE == "ruby"
+        return render_interpreted(name, locals, kind, **options) unless @templates.nil?
+      end
+      layout = options.delete(:layout) { "layouts/application" }
+      render_compiled(name, locals.merge(options), layout: layout)
+    end
+
+    def render_interpreted(name, locals = {}, kind = nil, **options)
+      if @templates.nil? && defined?(Hamster::CompiledViews)
+        layout = options.delete(:layout) { "layouts/application" }
+        locals = locals.merge(options)
+        return render_compiled(name, locals, layout: layout)
+      end
+      locals = locals.merge(options) unless options.empty?
+      instructions = @templates && @templates[name]
+      raise Error, "missing template #{name}" unless instructions
+
+      work = proc do
+        context = Context.new(name, locals)
+        output = instructions.map do |instruction|
+          case instruction[0]
+          when :literal then instruction[1]
+          when :value
+            value = context.fetch(instruction[1], instruction[3])
+            validate_url!(value, name, instruction[3]) if URL_ATTRIBUTES.include?(instruction[2])
+            if instruction[2].is_a?(String) && value.instance_of?(HTML::Fragment)
+              HTML.escape(value.to_s).to_s
+            else
+              HTML.escape(value).to_s
+            end
+          end
+        end.join
+        HTML::Fragment.new(output)
+      end
+      kind ||= name.start_with?("layouts/") ? "layout" : "template"
+      Hamster::Instrumentation.instrument("view.render", attributes: {"view.template" => name, "view.kind" => kind}) { work.call }
+    end
+
+    def validate_url!(value, name, line)
+      url = value.to_s
+      raise Error, "#{name}:#{line}: unsafe URL" unless url.start_with?("/") && !url.start_with?("//") && !url.match?(/[\x00-\x20\\<>"']/)
+    end
+
+    def path(name, params = {}, query: {}, **keywords)
+      raise Error, "route mapping is not configured" unless @routes
+      @routes.path(name, params, query: query, **keywords)
+    end
+  end
+end

data/lib/hamster/web.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "web/version"
+require_relative "web/instrumentation"
+require_relative "web/routing/base"
+require_relative "web/view"
+require_relative "web/html"
+require_relative "web/view/form"
+require_relative "web/http"
+require_relative "web/action/base"
+require_relative "web/context"
+require_relative "web/router"
+require_relative "web/application"

data/templates/app/.gitignore

@@ -0,0 +1,5 @@
+/.bundle/
+/bin/*-server
+/bin/*.tmp
+/tmp/
+/vendor/

data/templates/app/AGENTS.md

@@ -0,0 +1,8 @@
+# Application conventions
+
+- Keep one action per endpoint directory with a sibling view.html.erb.
+- Declare routes in app/routes/mappings.rb.
+- App Ruby files load through config/manifest.rb; do not add local requires.
+- Run bin/hamster manifest after editing application Ruby files or templates.
+- Run bin/hamster manifest:check before building.
+- Keep build-time code out of the Spinel runtime require chain.

data/templates/app/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+gem "hamster-web", "= __HAMSTER_VERSION__", require: "hamster/web"
+gem "spinel-spinner", "= 0.1.0.pre.1", require: "spinner"

data/templates/app/README.md

@@ -0,0 +1,32 @@
+# __APP_NAME__
+
+Run `bin/hamster setup` to install gems and vendor the locked Spin PostgreSQL driver.
+Spin and Spinel must already be installed. Configure DATABASE_USERNAME,
+DATABASE_PASSWORD, and optionally DATABASE_HOST and DATABASE_PORT for your local
+PostgreSQL server. DATABASE_NAME defaults to __APP_NAME___development.
+
+Setup and build apply three string-copy compatibility fixes to the pinned
+pg client for Spinel. The fixes are repeatable after spin vendor and reject
+an unknown driver revision; avoid editing vendored driver sources manually.
+
+Run `bin/hamster db:create`, `bin/hamster db:migrate`, `bin/hamster build`,
+then `bin/hamster serve`. Build does not require a database connection.
+An empty migration directory is valid; db:migrate initializes migration tracking.
+The server listens on http://127.0.0.1:4000 by default; configure HOST and PORT
+to override it. During framework development, install the local hamster-web
+gem before running setup.
+
+Run a deployed binary from the application root or set HAMSTER_APP_ROOT.
+Include db/migrations alongside the binary. PostgreSQL TLS is not supported
+by the current driver integration.
+
+Use `bin/hamster console` (alias `c`) for an IRB session with app, application,
+and database variables and a connection scope for record writes and queries.
+Use `bin/hamster db:validate` to check model table/column declarations against
+PostgreSQL without applying migrations. These commands use config/commands.rb,
+which is deliberately excluded from the compiled server's boot chain.
+
+Each endpoint has an action.rb and optional view.html.erb in app/routes/.
+Declare endpoints centrally in app/routes/mappings.rb. Run
+`bin/hamster manifest` after changing Ruby sources or templates and commit
+the generated manifest and view registry with your source changes.

data/templates/app/app/routes/home/index/action.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+module __APP_MODULE__
+  module Routes
+    module Home
+      module Index
+        class Action < Hamster::Action::Base
+          def call
+            respond(view: "home/index")
+          end
+        end
+      end
+    end
+  end
+end

data/templates/app/app/routes/home/index/view.html.erb

@@ -0,0 +1,2 @@
+<h1>Welcome to __APP_NAME__</h1>
+<p>Your Hamster application is running.</p>

data/templates/app/app/routes/mappings.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module __APP_MODULE__
+  module Routes
+    class Mappings < Hamster::Routing::Base
+      get "/", to: Home::Index::Action, as: :root
+    end
+  end
+end

data/templates/app/app/views/layouts/application.html.erb

@@ -0,0 +1,3 @@
+<%# locals: title %>
+<!doctype html><html><head><meta charset="utf-8"><title><%= title %></title></head>
+<body><main><%= yield %></main></body></html>

data/templates/app/bin/hamster

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "hamster/cli"
+exit Hamster::CLI.run(ARGV)

data/templates/app/bin/server

@@ -0,0 +1,8 @@
+require "spinner"
+require_relative "../config/application"
+application = __APP_MODULE__.build
+begin
+  Spinner::Server.new(application, host: ENV.fetch("HOST", "127.0.0.1"), port: ENV.fetch("PORT", "4000").to_i).run
+ensure
+  application.shutdown
+end

data/templates/app/config/application.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require "hamster/web"
+require_relative "database"
+require_relative "manifest"
+
+module __APP_MODULE__
+  def self.build
+    Hamster::View.configure(site_name: "__APP_NAME__", routes: Routes::Mappings)
+    database = Hamster::Database.new(database_configuration, migrations_path: File.join(root, "db/migrations"))
+    begin
+      database.verify!
+      Hamster::Application.new(routes: Routes::Mappings, database: database)
+    rescue StandardError
+      database.shutdown
+      raise
+    end
+  end
+
+  def self.validate_queries!
+  end
+end
+
+Hamster::View.configure(site_name: "__APP_NAME__", routes: __APP_MODULE__::Routes::Mappings)

data/templates/app/config/commands.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# CRuby command adapter; keep it out of the compiled server require chain.
+require_relative "application"
+
+module Hamster
+  module ApplicationCommands
+    def self.build
+      __APP_MODULE__.build
+    end
+
+    def self.database
+      Hamster::Database.new(__APP_MODULE__.database_configuration,
+                           migrations_path: File.join(__APP_MODULE__.root, "db/migrations"))
+    end
+  end
+end

data/templates/app/config/database.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+if RUBY_ENGINE == "ruby"
+  $LOAD_PATH.unshift(File.expand_path("../vendor/packages/pg-0.2.0", __dir__))
+end
+require "hamster/database/postgres"
+
+module __APP_MODULE__
+  def self.root
+    if RUBY_ENGINE == "ruby"
+      File.expand_path("..", __dir__)
+    else
+      ENV.fetch("HAMSTER_APP_ROOT", Dir.pwd)
+    end
+  end
+
+  def self.database_configuration
+    Hamster::Database::Configuration.from_env(app_name: "__APP_NAME__")
+  end
+end

data/templates/app/config/hamster.json

@@ -0,0 +1 @@
+{"name":"__APP_NAME__","namespace":"__APP_MODULE__"}

data/templates/app/spin.lock

@@ -0,0 +1,6 @@
+# generated by spin lock -- diff me, don't edit me
+
+[lock.pg]
+version = "0.2.0"
+git = "https://github.com/rubys/spinel-pg.git"
+ref = "5ff0188b0e8dffc88337723411ac725ee2659ff7"

data/templates/app/spin.toml

@@ -0,0 +1,2 @@
+[dependencies]
+pg = { git = "https://github.com/rubys/spinel-pg.git", ref = "5ff0188b0e8dffc88337723411ac725ee2659ff7" }

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: hamster-web
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.2
+platform: ruby
+authors:
+- Dillon Wyatt
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: spinel-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre.1
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Hamster provides a compiled Spinel web runtime and a CLI for generating
+  applications.
+email:
+- dostaglou@gmail.com
+executables:
+- hamster
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/hamster
+- lib/hamster/build/manifest.rb
+- lib/hamster/build/postgres_compatibility.rb
+- lib/hamster/build/query_accessors.rb
+- lib/hamster/build/view_compiler.rb
+- lib/hamster/cli.rb
+- lib/hamster/console.rb
+- lib/hamster/data.rb
+- lib/hamster/data/persistence.rb
+- lib/hamster/data/query.rb
+- lib/hamster/data/read/compiler.rb
+- lib/hamster/data/read/decoder.rb
+- lib/hamster/data/read/nodes.rb
+- lib/hamster/data/read/relation.rb
+- lib/hamster/data/read/schema.rb
+- lib/hamster/data/read/validator.rb
+- lib/hamster/data/record.rb
+- lib/hamster/data/table.rb
+- lib/hamster/database/admin.rb
+- lib/hamster/database/configuration.rb
+- lib/hamster/database/connection.rb
+- lib/hamster/database/database.rb
+- lib/hamster/database/errors.rb
+- lib/hamster/database/pool.rb
+- lib/hamster/database/postgres.rb
+- lib/hamster/database/result.rb
+- lib/hamster/schema_validation.rb
+- lib/hamster/web.rb
+- lib/hamster/web/action/base.rb
+- lib/hamster/web/application.rb
+- lib/hamster/web/context.rb
+- lib/hamster/web/html.rb
+- lib/hamster/web/http.rb
+- lib/hamster/web/instrumentation.rb
+- lib/hamster/web/router.rb
+- lib/hamster/web/routing/base.rb
+- lib/hamster/web/version.rb
+- lib/hamster/web/view.rb
+- lib/hamster/web/view/form.rb
+- templates/app/.gitignore
+- templates/app/AGENTS.md
+- templates/app/Gemfile
+- templates/app/README.md
+- templates/app/app/routes/home/index/action.rb
+- templates/app/app/routes/home/index/view.html.erb
+- templates/app/app/routes/mappings.rb
+- templates/app/app/views/layouts/application.html.erb
+- templates/app/bin/hamster
+- templates/app/bin/server
+- templates/app/config/application.rb
+- templates/app/config/commands.rb
+- templates/app/config/database.rb
+- templates/app/config/hamster.json
+- templates/app/db/migrations/.keep
+- templates/app/spin.lock
+- templates/app/spin.toml
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: A Spinel web framework and application generator
+test_files: []