itsi 0.1.20 → 0.2.2

data/gems/server/lib/itsi/server/config/middleware/endpoint/controller.md

@@ -0,0 +1,186 @@
+---
+title: Controller
+url: /middleware/controller
+prev: endpoint/
+---
+
+
+Instead of supplying an [endpoint](/middleware/endpoint) body inline, you can also reference a method by name (as a `:symbol`).
+Itsi will attach the method, resolved by name within the current controller scope, to the endpoint.
+
+E.g.
+```ruby {filename=Itsi.rb}
+controller UserController.new
+get "", :index
+```
+
+The default controller scope is the parent `Itsi.rb` config file.
+However you can use the `controller` middleware to explicitly set a controller scope per [location](/middleware/location) block. All named endpoints will then be satisfied by the current controller.
+
+{{< callout >}}
+Itsi will check for the presence and structure of all:
+* Controller methods
+* [Schemas](/middleware/schemas)
+
+at **boot time** ensuring that you can't be caught out by naming mismatches at runtime, or during a hot-reload.
+If Itsi boots successfully, the controller methods exist and accept the correct parameters.
+{{</ callout >}}
+
+## Basic Example
+```ruby {filename=Itsi.rb}
+controller UserController.new
+```
+
+{{< callout  >}}
+There are no special requirements for a controller in Itsi, it can be *any* ruby object, so long as it responds to the methods attached to the endpoint and accepts the request object as the first argument. This could be a singleton module, an instance, a struct etc.
+{{< /callout >}}.
+
+### Detailed Example
+
+```ruby {filename=Itsi.rb}
+
+require_relative "schemas"
+require_relative "user_controller"
+
+location "/users*" do
+  controller UserController.new
+  post "/", :create
+end
+
+def home(req)
+  req.respond "I'm home"
+end
+# Default controller is just the top-level Itsi scope
+get "/", :home
+```
+
+
+```ruby {filename=user_controller.rb}
+class UserController
+
+  def initialize()
+    # One time controller set-up here
+  end
+
+  def create(request, params: UserInputSchema, response_format: UserResponseSchema)
+    user = User.create!(params)
+    request.created \
+      json: {
+        id: user.id,
+        email: user.email,
+        full_name: "#{user.first_name} #{user.last_name}",
+        created_at: user.created_at.iso8601,
+        address: {
+          street: user.address.street,
+          city: user.address.city,
+          postcode: user.address.postcode
+        }
+      },
+      as: response_format
+  end
+end
+
+# Dummy data model.
+Address = Struct.new(:street, :city, :postcode, :country, keyword_init: true)
+
+class User < Struct.new(
+  :id, :email, :first_name, :last_name, :created_at,
+  :address, :age, :active, :roles, keyword_init: true)
+  def self.create!(params)
+    self.new(
+      id: Random.rand(1000000...99999999),
+      address: Address.new(params.delete :address),
+      **params,
+      created_at: Time.now
+    )
+  end
+end
+
+```
+
+```ruby {filename=schemas.rb}
+AddressSchema = {
+  _required: %i[street city postcode],
+  street: String,
+  city: String,
+  postcode: String,
+  country: String # Optional
+}
+
+UserInputSchema = {
+  _required: %i[first_name last_name email address],
+  first_name: String,
+  last_name: String,
+  email: String,
+  age: Integer,
+  active: :Boolean,
+  roles: Array[String],
+  address: AddressSchema
+}
+
+UserResponseSchema = {
+  _required: %i[id email full_name],
+  id: Integer,
+  email: String,
+  full_name: String,
+  created_at: String,
+  address: AddressSchema
+}
+```
+
+```bash
+curl http://0.0.0.0:3000/users -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"id": 3, "age": "nine", "first_name":8,"last_name":"test","email":"test", "address": {"street":"1 Main Street","city":"Wellington","postcode":1234}}'
+
+{"error":"Validation failed: Invalid value for Integer at age: \"nine\" (invalid value for Integer(): \"nine\")"}%
+```
+
+
+```bash
+curl http://0.0.0.0:3000/users \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{"id": 3, "age": "ninety-nine", "first_name":"John","last_name":"Smith","email":"test", "address": {"street":"1 Main Street","city":"Wellington","postcode":1234}}'
+```
+```json
+{
+  "error":"Validation failed: Invalid value for Integer at age: \"ninety-nine\" (invalid value for Integer(): \"nine\")"}%
+```
+
+```bash
+curl http://0.0.0.0:3000/users \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{"id": 3, "age": 99, "first_name":"John","last_name":"Smith","email":"test", "address": {"street":"1 Main Street","city":"Wellington","postcode":1234}}'
+```
+```json
+{
+  "id":46895213,
+  "email":"test",
+  "full_name":"John Smith",
+  "created_at":"2025-04-20T08:47:28+12:00",
+  "address":{
+    "street":"1 Main Street",
+    "city":"Wellington",
+    "postcode":"1234",
+    "country":null
+  }
+}
+```
+
+```bash
+curl http://0.0.0.0:3000/
+I'm home
+```
+
+### Module as a Controller
+```ruby {filename=Itsi.rb}
+module UserController
+  module_function
+  def create(req, params)
+    req.ok json: User.create(params)
+  end
+end
+
+controller User
+post "/", :create
+```

data/gems/server/lib/itsi/server/config/middleware/endpoint/controller.rb

@@ -0,0 +1,33 @@
+module Itsi
+  class Server
+    module Config
+      class Controller < Middleware
+
+        insert_text <<~SNIPPET
+        controller ${1:MyControllerClass.new}
+        SNIPPET
+
+        detail "Sets the controller scope for named endpoints"
+
+        schema do
+          Type(Object) & Required()
+        end
+
+        def initialize(location, controller=nil)
+          super
+
+          if controller
+            location.instance_eval{ @controller = controller}
+          end
+        end
+
+        def build!
+          if !@params
+            location.instance_eval{ @controller }
+          end
+        end
+
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/middleware/endpoint/delete.md

@@ -0,0 +1,12 @@
+---
+title: Delete
+url: /middleware/delete
+---
+
+The `delete` middleware is an [endpoint](/middleware/endpoint) restricted to DELETE requests.
+
+Endpoints are light-weight inline middleware that can be used to handle requests without the need for a fully fledged Rack-based application framework.
+Endpoints can optionally be directed to a controller, and use request and response schema enforcement.
+
+You can use endpoints and rack-apps simultaneously.
+See [endpoint](/middleware/endpoint).

data/gems/server/lib/itsi/server/config/middleware/endpoint/delete.rb

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+      class Delete < Middleware
+
+        insert_text [
+          <<~SNIPPET,
+          delete "${1:/path}", :${2:handler}
+          SNIPPET
+          <<~SNIPPET,
+          delete "${1:/path}" do |req|
+          $2
+          end
+          SNIPPET
+          <<~SNIPPET,
+          delete "${1:/path}" do |req, params|
+          $2
+          end
+          SNIPPET
+        ]
+
+        detail ["A light-weight DELETE endpoint (controller)", "A light-weight DELETE endpoint (inline block)", "A light-weight DELETE endpoint (inline params)"]
+
+        schema do
+          {
+            paths: Array(Or(Type(String), Type(Regexp))),
+            handler: Type(Proc) & Required(),
+            http_methods: Array(Type(String)),
+            nonblocking: Bool()
+          }
+        end
+
+        def initialize(location, path="", handler=nil, http_methods: [], nonblocking: false, &handler_proc)
+          location.endpoint(path, handler, http_methods: ["DELETE"], nonblocking: nonblocking, &handler_proc)
+        end
+
+        def build!
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/middleware/endpoint/endpoint.rb

@@ -0,0 +1,99 @@
+module Itsi
+  class Server
+    module Config
+      class Endpoint < Middleware
+
+        InvalidHandlerException = Class.new(StandardError)
+
+        insert_text [
+          <<~SNIPPET,
+          endpoint "${1:/path}", :${2:handler}
+          SNIPPET
+          <<~SNIPPET,
+          endpoint "${1:/path}" do |req|
+          $2
+          end
+          SNIPPET
+          <<~SNIPPET,
+          endpoint "${1:/path}" do |req, params|
+          $2
+          end
+          SNIPPET
+        ]
+
+        detail ["A light-weight HTTP endpoint (controller)", "A light-weight HTTP endpoint (inline block)", "A light-weight HTTP endpoint (inline params)"]
+
+        schema do
+          {
+            paths: Array(Or(Type(String), Type(Regexp))),
+            handler: Type(Proc) & Required(),
+            http_methods: Array(Type(String)),
+            nonblocking: Bool()
+          }
+        end
+
+        def initialize(location, path="", handler=nil, http_methods: [], nonblocking: false, &handler_proc)
+          raise "Can not combine a controller method and inline handler" if handler && handler_proc
+          handler_proc = location.controller.method(handler).to_proc if handler.is_a?(Symbol) || handler.is_a?(String)
+
+          super(
+            location,
+            { paths: Array(path), handler: handler_proc, http_methods: http_methods, nonblocking: nonblocking }
+          )
+
+          num_required, keywords = Itsi::Server::TypedHandlers::SourceParser.extract_expr_from_source_location(handler_proc)
+          params_schema = keywords[:params]
+          response_schema = keywords[:response_format]
+          exception = nil
+          if params_schema && num_required > 1
+            exception = InvalidHandlerException.new("Cannot accept multiple required parameters in a single endpoint. A single typed or untyped params argument is supported")
+          end
+          if num_required > 2
+            exception = InvalidHandlerException.new("Cannot accept more than two required parameters in a single endpoint. An can either accept a single request argument, or a request and a params argument (which may be typed or untyped). You can also use keyword arguments to anchor response types")
+          end
+          if num_required == 0
+            exception = InvalidHandlerException.new("Cannot accept zero required parameters in a single endpoint. Endpoint must accept a request parameter")
+          end
+          if response_schema && !(handler_proc.binding.eval(response_schema) rescue false)
+            exception = InvalidHandlerException.new("Response Schema by name `#{response_schema}` not found.")
+          end
+          if params_schema && !(handler_proc.binding.eval(params_schema) rescue false)
+            exception = InvalidHandlerException.new("Params Schema by name `#{params_schema}` not found.")
+          end
+
+          if exception
+            exception.set_backtrace([handler_proc.source_location.join(":")] + caller)
+            raise exception
+          end
+
+          accepts_params = !params_schema.nil? || num_required > 1
+
+          if accepts_params
+            @params[:handler] = Itsi::Server::TypedHandlers.handler_for(@params[:handler], params_schema)
+          end
+        end
+
+        def build!
+          params = @params
+          app = { preloader: -> { params[:handler] }, nonblocking: @params[:nonblocking] }
+
+          if @params[:paths] == [""] && @params[:http_methods].empty?
+            location.middleware[:app] = app
+            location.location("*") do
+              @middleware[:app] = app
+            end
+          else
+            @params[:paths] << "" if @params[:paths].empty?
+            @params[:paths] = @params[:paths].flat_map do |p|
+              stripped_trailing = p[/(.*)\/?$/, 1]
+              [stripped_trailing, stripped_trailing + "/"]
+            end.uniq
+            location.location(*@params[:paths], methods: @params[:http_methods]) do
+              @middleware[:app] = app
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/middleware/endpoint/get.md

@@ -0,0 +1,12 @@
+---
+title: Get
+url: /middleware/get
+---
+
+The `get` middleware is an [endpoint](/middleware/endpoint) restricted to GET requests.
+
+Endpoints are light-weight inline middleware that can be used to handle requests without the need for a fully fledged Rack-based application framework.
+Endpoints can optionally be directed to a controller, and use request and response schema enforcement.
+
+You can use endpoints and rack-apps simultaneously.
+See [endpoint](/middleware/endpoint).

data/gems/server/lib/itsi/server/config/middleware/endpoint/get.rb

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+      class Get < Middleware
+
+        insert_text [
+          <<~SNIPPET,
+          get "${1:/path}", :${2:handler}
+          SNIPPET
+          <<~SNIPPET,
+          get "${1:/path}" do |req|
+          $2
+          end
+          SNIPPET
+          <<~SNIPPET,
+          get "${1:/path}" do |req, params|
+          $2
+          end
+          SNIPPET
+        ]
+
+        detail ["A light-weight GET endpoint (controller)", "A light-weight GET endpoint (inline block)", "A light-weight HTTP endpoint (inline params)"]
+
+        schema do
+          {
+            paths: Array(Or(Type(String), Type(Regexp))),
+            handler: Type(Proc) & Required(),
+            http_methods: Array(Type(String)),
+            nonblocking: Bool()
+          }
+        end
+
+        def initialize(location, path="", handler=nil, http_methods: [], nonblocking: false, &handler_proc)
+          location.endpoint(path, handler, http_methods: ["GET", "HEAD"], nonblocking: nonblocking, &handler_proc)
+        end
+
+        def build!
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/middleware/endpoint/http_request.md

@@ -0,0 +1,44 @@
+---
+title: HTTP Request
+url: /middleware/http_request
+---
+
+An [endpoint](/middleware/endpoint), always accepts a  `request` object as the first parameter.
+E.g.
+
+```ruby {filename=Itsi.rb}
+get "/" do |req|
+end
+```
+
+
+end
+
+| Method           | Description                                                                 |
+|------------------|-----------------------------------------------------------------------------|
+| `path`           | Retrieves the path of the HTTP request.                                    |
+| `script_name`    | Retrieves the script name of the HTTP request.                             |
+| `query_string`   | Retrieves the query string from the HTTP request.                          |
+| `content_type`   | Retrieves the content type of the HTTP request.                            |
+| `content_length` | Retrieves the content length of the HTTP request.                          |
+| `request_method` | Retrieves the HTTP method (e.g., GET, POST) of the request.                |
+| `version`        | Retrieves the HTTP version of the request.                                 |
+| `rack_protocol`  | Retrieves the Rack protocol version used in the request.                   |
+| `host`           | Retrieves the host of the HTTP request.                                    |
+| `headers`        | Retrieves all headers from the HTTP request.                               |
+| `uri`            | Retrieves the full URI of the HTTP request.                                |
+| `header`         | Retrieves the value of a specific header from the HTTP request.            |
+| `[]`             | Alias for `header`, retrieves the value of a specific header.              |
+| `scheme`         | Retrieves the scheme (e.g., http, https) of the HTTP request.              |
+| `remote_addr`    | Retrieves the remote address of the client making the request.             |
+| `port`           | Retrieves the port number of the HTTP request.                             |
+| `body`           | Retrieves the body of the HTTP request (As an IO).                         |
+| `response`       | Retrieves the [response](/middleware/http_response) object associated with the HTTP request.            |
+| `json?`          | Checks if the request content type is JSON.                                |
+| `html?`          | Checks if the request content type is HTML.                                |
+| `url_encoded?`   | Checks if the request content type is URL-encoded.                         |
+| `multipart?`     | Checks if the request content type is multipart.                           |
+| `url_params`     | Retrieves the URL parameters from the HTTP request.                        |
+| `#<status_name>` | Writes a response with the specified status code and closes the response. |
+| `respond`       | Writes a response with the specified status code and closes the response. |
+| `query_params`     | Retrieves the query parameters from the HTTP request.                      |

data/gems/server/lib/itsi/server/config/middleware/endpoint/http_response.md

@@ -0,0 +1,39 @@
+---
+title: HTTP Response
+url: /middleware/http_response
+---
+
+Within the body of an [endpoint](/middleware/endpoint), you can access the `#response` object on the incoming request for more fine-grained control over the response body.
+
+
+{{< callout >}}
+Itsi allows you to efficiently keep long-running responses open, and write to these asynchronously.
+Just remember to close them eventually...
+
+{{< /callout >}}
+
+
+E.g.
+
+```ruby {filename=Itsi.rb}
+
+get "/" do |req|
+  resp = req.response
+  resp << "Stream some content"
+
+  # Eventually... (This does not have to occur within the body of this method.)
+  resp.close
+end
+```
+
+
+| Method           | Description                                                                 |
+|------------------|-----------------------------------------------------------------------------|
+| `#<<`            | Appends content to the response body (allows you to stream content).                                       |
+| `#send_and_close`| Sends a single response chunk and closes the connection.                              |
+| `status=`        | Sets the HTTP status code for the response.                                |
+| `add_header`     | Adds a header to the response.                                             |
+| `accept`         | Retrieves the accepted content types from the request.                    |
+| `close`          | Closes the response stream.                                               |
+| `json?`          | Checks if the response content type is JSON.                              |
+| `html?`          | Checks if the response content type is HTML.                              |

data/gems/server/lib/itsi/server/config/middleware/endpoint/patch.md

@@ -0,0 +1,12 @@
+---
+title: Patch
+url: /middleware/patch
+---
+
+The `patch` middleware is an [endpoint](/middleware/endpoint) restricted to PATCH requests.
+
+Endpoints are light-weight inline middleware that can be used to handle requests without the need for a fully fledged Rack-based application framework.
+Endpoints can optionally be directed to a controller, and use request and response schema enforcement.
+
+You can use endpoints and rack-apps simultaneously.
+See [endpoint](/middleware/endpoint).

data/gems/server/lib/itsi/server/config/middleware/endpoint/patch.rb

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+      class Patch < Middleware
+
+        insert_text [
+          <<~SNIPPET,
+          patch "${1:/path}", :${2:handler}
+          SNIPPET
+          <<~SNIPPET,
+          patch "${1:/path}" do |req|
+          $2
+          end
+          SNIPPET
+          <<~SNIPPET,
+          patch "${1:/path}" do |req, params|
+          $2
+          end
+          SNIPPET
+        ]
+
+        detail ["A light-weight PATCH endpoint (controller)", "A light-weight PATCH endpoint (inline block)", "A light-weight PATCH endpoint (inline params)"]
+
+        schema do
+          {
+            paths: Array(Or(Type(String), Type(Regexp))),
+            handler: Type(Proc) & Required(),
+            http_methods: Array(Type(String)),
+            nonblocking: Bool()
+          }
+        end
+
+        def initialize(location, path="", handler=nil, http_methods: [], nonblocking: false, &handler_proc)
+          location.endpoint(path, handler, http_methods: ["PATCH"], nonblocking: nonblocking, &handler_proc)
+        end
+
+        def build!
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/middleware/endpoint/post.md

@@ -0,0 +1,12 @@
+---
+title: Post
+url: /middleware/post
+---
+
+The `post` middleware is an [endpoint](/middleware/endpoint) restricted to POST requests.
+
+Endpoints are light-weight inline middleware that can be used to handle requests without the need for a fully fledged Rack-based application framework.
+Endpoints can optionally be directed to a controller, and use request and response schema enforcement.
+
+You can use endpoints and rack-apps simultaneously.
+See [endpoint](/middleware/endpoint).

data/gems/server/lib/itsi/server/config/middleware/endpoint/post.rb

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+      class Post < Middleware
+
+        insert_text [
+          <<~SNIPPET,
+          post "${1:/path}", :${2:handler}
+          SNIPPET
+          <<~SNIPPET,
+          post "${1:/path}" do |req|
+          $2
+          end
+          SNIPPET
+          <<~SNIPPET,
+          post "${1:/path}" do |req, params|
+          $2
+          end
+          SNIPPET
+        ]
+
+        detail ["A light-weight POST endpoint (controller)", "A light-weight POST endpoint (inline block)", "A light-weight POST endpoint (inline params)"]
+
+        schema do
+          {
+            paths: Array(Or(Type(String), Type(Regexp))),
+            handler: Type(Proc) & Required(),
+            http_methods: Array(Type(String)),
+            nonblocking: Bool()
+          }
+        end
+
+        def initialize(location, path="", handler=nil, http_methods: [], nonblocking: false, &handler_proc)
+          location.endpoint(path, handler, http_methods: ["POST"], nonblocking: nonblocking, &handler_proc)
+        end
+
+        def build!
+        end
+      end
+    end
+  end
+end

data/gems/server/lib/itsi/server/config/middleware/endpoint/put.md

@@ -0,0 +1,12 @@
+---
+title: Put
+url: /middleware/put
+---
+
+The `put` middleware is an [endpoint](/middleware/endpoint) restricted to PUT requests.
+
+Endpoints are light-weight inline middleware that can be used to handle requests without the need for a fully fledged Rack-based application framework.
+Endpoints can optionally be directed to a controller, and use request and response schema enforcement.
+
+You can use endpoints and rack-apps simultaneously.
+See [endpoint](/middleware/endpoint).

data/gems/server/lib/itsi/server/config/middleware/endpoint/put.rb

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+      class Put < Middleware
+
+        insert_text [
+          <<~SNIPPET,
+          put "${1:/path}", :${2:handler}
+          SNIPPET
+          <<~SNIPPET,
+          put "${1:/path}" do |req|
+          $2
+          end
+          SNIPPET
+          <<~SNIPPET,
+          put "${1:/path}" do |req, params|
+          $2
+          end
+          SNIPPET
+        ]
+
+        detail ["A light-weight PUT endpoint (controller)", "A light-weight PUT endpoint (inline block)", "A light-weight PUT endpoint (inline params)"]
+
+        schema do
+          {
+            paths: Array(Or(Type(String), Type(Regexp))),
+            handler: Type(Proc) & Required(),
+            http_methods: Array(Type(String)),
+            nonblocking: Bool()
+          }
+        end
+
+        def initialize(location, path="", handler=nil, http_methods: [], nonblocking: false, &handler_proc)
+          location.endpoint(path, handler, http_methods: ["PUT"], nonblocking: nonblocking, &handler_proc)
+        end
+
+        def build!
+        end
+      end
+    end
+  end
+end