itsi-server 0.1.1 → 0.2.2

data/lib/itsi/server/config/options/preload.rb

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class Preload < Option
+
+        insert_text <<~SNIPPET
+        preload ${1|true,false,:preload|} # Preload
+        SNIPPET
+
+        detail "Configures whether all apps and middleware are preloaded before forking, just specific gem groups, or nothing. Has no effect if running in single mode."
+
+        schema do
+          Or(Bool(), Type(Symbol)).default(false)
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/recv_buffer_size.md

@@ -0,0 +1,15 @@
+---
+title: Receive Buffer Size
+url: /options/recv_buffer_size
+---
+
+Configures the size of the receive buffer for the socket. Larger buffer sizes can improve performance for high-throughput applications but may increase memory usage. The default value is 262,144 bytes.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+recv_buffer_size 262_144
+```
+
+```ruby {filename=Itsi.rb}
+recv_buffer_size 1_048_576
+```

data/lib/itsi/server/config/options/recv_buffer_size.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class RecvBufferSize < Option
+
+        insert_text <<~SNIPPET
+        recv_buffer_size ${1|262_144,1_048_576|}
+        SNIPPET
+
+        detail "Specifies the size of the receive buffer for the socket. Larger buffer sizes can improve performance for high-throughput applications but may increase memory usage. The default value is 262,144 bytes."
+
+        schema do
+          (Type(Integer) & Range(1..Float::INFINITY) & Required()).default(262_144)
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/redirect_http_to_https.md

@@ -0,0 +1,21 @@
+---
+title: Redirect HTTP to HTTPS
+url: /options/redirect_http_to_https
+---
+This simple option installs a location block to redirect all HTTP traffic to HTTPS.
+
+```ruby {filename=Itsi.rb}
+redirect_http_to_https!
+```
+
+It is an alias for:
+```ruby
+location protocols: [:http] do
+  redirect \
+    to: "https://{host}{path_and_query}", \
+    type: "moved_permanently"
+end
+```
+
+It is subject to ordinary [location](/middleware/location) resolution rules.
+To make sure this rule takes precedence, place it *above* other locations in the `Itsi.rb` file

data/lib/itsi/server/config/options/redirect_http_to_https.rb

@@ -0,0 +1,30 @@
+module Itsi
+  class Server
+    module Config
+      class RedirectHttpToHttps < Option
+
+        insert_text <<~SNIPPET
+        redirect_http_to_https! # Install a location block to redirect HTTP to HTTPS
+                                # (Only works if listening on ports 443 and 80).
+                                # For non-conventional or development ports use a manual redirect
+        SNIPPET
+
+        detail "Install a location block to redirect HTTP to HTTPS."
+
+        def self.option_name
+          :redirect_http_to_https!
+        end
+
+        def build!
+          location.instance_eval do
+            location protocols: [:http] do
+              redirect \
+                to: "https://{host}{path_and_query}", \
+                type: "moved_permanently"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/request_timeout.md

@@ -0,0 +1,23 @@
+---
+title: Request Timeout
+url: /options/request_timeout
+---
+
+Sets the maximum duration (in seconds) allowed for the entire request to complete. If exceeded, the request will be terminated.
+
+
+### Default
+
+```ruby {filename=Itsi.rb}
+request_timeout 300  # 5 minutes
+```
+### Example
+
+```ruby {filename=Itsi.rb}
+request_timeout 60  # 1 minute
+```
+
+
+{{< callout type="warn" >}}
+If the request is held-up inside a Ruby worker, the worker will be gracefully restarted (as killing in-progress threads is not safe).
+{{< /callout >}}

data/lib/itsi/server/config/options/request_timeout.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class RequestTimeout < Option
+
+        insert_text <<~SNIPPET
+        request_timeout 300.0 # Request Timeout in Seconds
+        SNIPPET
+
+        detail "Set Request Timeout"
+
+        schema do
+          (Type(Float) & Required()).default(300.0) # Default 5 minutes
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/reuse_address.md

@@ -0,0 +1,16 @@
+---
+title: Reuse Address
+url: /options/reuse_address
+---
+
+Configures whether the server should bind to the underlying socket using the `SO_REUSEADDR` option.
+This optiondetermines whether the server allows the reuse of local addresses during binding. This can be useful in scenarios where a socket needs to be quickly rebound without waiting for the operating system to release the address.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+reuse_address true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_address false
+```

data/lib/itsi/server/config/options/reuse_address.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class ReuseAddress < Option
+
+        insert_text <<~SNIPPET
+        reuse_address ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether the server should set the reuse_address option on the underlying socket."
+
+        schema do
+          (Bool() & Required()).default(true)
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/reuse_port.md

@@ -0,0 +1,16 @@
+---
+title: Reuse Port
+url: /options/reuse_port
+---
+
+Configures whether the server should bind to the underlying socket using the `SO_REUSEPORT` option.
+This option determines whether multiple sockets can listen on the same IP and port combination, which can improve load balancing and fault tolerance in multi-threaded or multi-process server applications.
+
+## Configuration
+```ruby {filename=Itsi.rb}
+reuse_port true
+```
+
+```ruby {filename=Itsi.rb}
+reuse_port false
+```

data/lib/itsi/server/config/options/reuse_port.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class ReusePort < Option
+
+        insert_text <<~SNIPPET
+        reuse_port ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether the server should set the reuse_port option on the underlying socket."
+
+        schema do
+          (Bool() & Required()).default(true)
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/scheduler_threads.md

@@ -0,0 +1,34 @@
+---
+title: Scheduler Threads
+url: /options/scheduler_threads
+---
+
+You can explicitly spawn a pool of non-blocking scheduler threads and divide work across traditional blocking and non-blocking threads, using [location](/middleware/location) blocks.
+
+This allows you to safely dip your toes into using non-blocking threads for specific I/O heavy operations without having to port an entire application to non-blocking I/O.
+
+To use blocking and non-blocking threads in conjunction you need to perform several steps.
+1. Configure a thread pool using [threads](/middleware/threads)
+2. Configure a **separate** non-blocking thread pool using [scheduler_threads](/middleware/scheduler_threads) (By opting into this option you automatically make the ordinary thread pool blocking)
+3. Enable a [fiber_scheduler](/options/fiber_scheduler)
+4. Mount your app as non-blocking for selected routes. (Using either [run](/middleware/run), [rackup_file](/middleware/rackup_file) or [endpoint](/middleware/endpoint))
+
+## Configuration
+Here is an example configuration of the all of the above E.g.
+
+```ruby {filename=Itsi.rb}
+
+threads 3 # 3 threads (opting into scheduler threads make these blocking)
+scheduler_threads 1 # 1 non-blocking scheduler thread
+fiber_scheduler true
+
+# We mount the same app *twice*.
+# For a specific route prefix, all requests will be sent to non blocking threads.
+# All others fall through to the default mount
+location "/heavy_io/*" do
+  rackup_file "./config.ru", nonblocking: true
+end
+
+rackup_file "./config.ru"
+
+```

data/lib/itsi/server/config/options/scheduler_threads.rb

@@ -0,0 +1,17 @@
+module Itsi
+  class Server
+    module Config
+      class SchedulerThreads < Option
+
+        insert_text "scheduler_threads ${1|1,2,Etc.nprocessors|} # Number of non-blocking scheduler threads to run per worker"
+
+        detail "Number of non-blocking scheduler threads to run per worker"
+
+        schema do
+          Range(1..255)
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/shutdown_timeout.md

@@ -0,0 +1,17 @@
+---
+title: Shutdown Timeout
+url: /options/shutdown_timeout
+---
+
+Sets the timeout for graceful shutdown of the server. Itsi will stop accepting new connections immediately after receiving a shutdown signal. Existing connections will be allowed to complete their requests within the specified timeout. Any connections that do not complete within the timeout will be forcefully closed.
+
+### Default
+
+```ruby {filename=Itsi.rb}
+shutdown_timeout 5.0  # 5 seconds
+```
+### Example
+
+```ruby {filename=Itsi.rb}
+shutdown_timeout 20.0  # 20 seconds
+```

data/lib/itsi/server/config/options/shutdown_timeout.rb

@@ -0,0 +1,19 @@
+module Itsi
+  class Server
+    module Config
+      class PinWorkerCores < Option
+
+        insert_text <<~SNIPPET
+        pin_worker_cores ${1|true,false|} # Configure whether worker processes should attempt to pin to a single CPU core.
+        SNIPPET
+
+        detail "Configure whether worker processes should attempt to pin to a single CPU core"
+
+        schema do
+          (Bool() & Required()).default(true) # Default 5 seconds
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/stream_body.md

@@ -0,0 +1,32 @@
+---
+title: Stream Body
+url: /options/stream_body
+---
+
+The **stream_body** option controls whether Itsi buffers the request body in memory before passing it to your application code. Several Rack applications rely on this behaviour (so that the request can be rewound and/or parsed in its entirety before being processed), for this reason the default behaviour is `true`.
+However for light-weight requests that benefit from not holding the entire request body in memory, you can set this option to `false`.
+
+
+{{< callout >}}
+To prevent excessive memory usage, Itsi will store any large buffered request bodies in temporary storage on the file-system when request body streaming is disabled.
+{{< /callout >}}
+
+
+
+Streaming bodies cooperate particularly well with [Fiber scheduler](/options/fiber_scheduler) mode, to allow you to process many large and long-running incoming data streams simultaneously. For this use case, be sure to adjust both [max_body](/options/max_body) and [request_timeout](/options/request_timeout) to ensure large incoming requests are not terminated prematurely.
+
+
+
+## Configuration File
+
+```ruby
+# Disable streaming the request body
+stream_body false
+
+# Enable streaming the request body
+stream_body true
+post("/test_stream") do |req|
+  # req.body is an IO
+  first_five_bytes = req.body.read(5)
+end
+```

data/lib/itsi/server/config/options/stream_body.rb

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class StreamBody < Option
+
+        insert_text <<~SNIPPET
+        stream_body ${1|true,false|}
+        SNIPPET
+
+        detail "Configures whether request bodies should be completed buffered *before* they are forwarded to the application."
+
+        schema do
+          Or(Bool(), Type(Symbol)).default(false)
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/threads.md

@@ -0,0 +1,44 @@
+---
+title: Threads
+url: /options/threads
+---
+Itsi supports running in threaded mode. Spawning more than one thread per worker is helpful for applications that require high concurrency and low latency.
+
+Note, that while threading allows for concurrent execution of tasks, it also introduces additional overhead due to context switching between threads.
+This overhead can be significant, especially when dealing with a large number of concurrent tasks.
+To minimize this overhead, it's recommended to keep the number of threads low, and tune this parameter based on your specific use case.
+
+When running Itsi in blocking mode, the total number of concurrent requests will be equal to `workers` x `threads`
+
+
+{{< callout >}}
+If you enable  a [fiber_scheduler](/options/fiber_scheduler), the threads will be non-blocking, unless you are using both [threads](/options/threads) and [scheduler_threads](/options/scheduler_threads) **together**.
+{{< /callout >}}
+
+
+## Configuration File
+The number of threads to use can be specified inside the configuration file (usually `./Itsi.rb` at the project root)
+using the `threads` function.
+
+## Examples
+```ruby {filename="Itsi.rb"}
+# Starts each worker with a single thread
+threads 1
+```
+
+```ruby {filename="Itsi.rb"}
+# Each worker will start 4 threads
+threads 4
+```
+
+Threads increase concurrency at the expense of memory usage and CPU overhead.
+For IO heavy workloads, consider using [non-blocking mode](/options/fiber_scheduler) instead, which can achieve higher concurrency with fewer threads.
+Non-blocking mode and threads can be used simultaneously in a hybrid configuration.
+
+## Command Line
+You can also override the number of threads using either the `-t` or `--threads` command line option.
+E.g.
+
+```bash
+itsi -t 3
+```

data/lib/itsi/server/config/options/threads.rb

@@ -0,0 +1,17 @@
+module Itsi
+  class Server
+    module Config
+      class Threads < Option
+
+        insert_text "threads ${1|1,2,Etc.nprocessors|} # Number of threads to run per worker"
+
+        detail "Number of threads to run per worker"
+
+        schema do
+          Range(1..255)
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/watch.md

@@ -0,0 +1,16 @@
+---
+title: Watch
+url: /options/watch
+---
+
+The `watch` option uses Itsi's built-in file watching mechanism to execute a list of commands each time any file matching the path glob parameter is modified.
+
+You can have several active watches at once.
+
+E.g.
+
+```ruby {filename=Itsi.rb}
+watch 'config/*.yml', [%w[npm run build], %w[bundle exec cache:mark_dirty]]
+
+watch 'app/**/*.rb', [%w[bundle exec itsi restart]]
+```

data/lib/itsi/server/config/options/watch.rb

@@ -0,0 +1,28 @@
+module Itsi
+  class Server
+    module Config
+      class Watch < Option
+
+        insert_text <<~SNIPPET
+        watch "${1:./**/*.rb}", [${2:%w[bundle exec itsi restart]}] # Run a command each time a watched set of files changes
+        SNIPPET
+
+        detail "Run a command each time a watched set of files changes"
+
+        def initialize(location, path, commands)
+          @path = path
+          @commands = commands
+          super(location, nil)
+        end
+
+        def build!
+          path, commands = @path, @commands
+          location.instance_eval do
+            @options[:notify_watchers] ||= []
+            @options[:notify_watchers] << [path, commands]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/worker_memory_limit.md

@@ -0,0 +1,22 @@
+---
+title: Worker Memory Limit
+url: /options/worker_memory_limit
+---
+
+The **Worker Memory Limit** option sets the maximum amount of memory a worker process can use before it is terminated. If an [`after_memory_threshold_reached`](/options/after_memory_limit_reached) hook is also set, you can define custom behaviour (e.g. an alert or exception notification) that should occur before the worker is rebooted.
+
+
+## Configuration File
+
+### Examples
+
+```ruby {filename="Itsi.rb"}
+worker_memory_limit 256 * 1024 ** 2 # 256 MB
+```
+
+```ruby {filename="Itsi.rb"}
+worker_memory_limit 256 * 1024 ** 2 # 256 MB
+after_memory_limit_reached do |pid|
+  send_slack_alert("Worker #{pid} exceeded memory limit")
+end
+```

data/lib/itsi/server/config/options/worker_memory_limit.rb

@@ -0,0 +1,18 @@
+module Itsi
+  class Server
+    module Config
+      class WorkerMemoryLimit < Option
+
+        insert_text <<~SNIPPET
+        worker_memory_limit ${1|256,512,1024,2048|} * 1024 ** 2 # Worker memory limit in bytes
+        SNIPPET
+
+        detail "Set the maximum amount of memory a worker process can use before it is terminated."
+
+        schema do
+          Type(Integer) & Required()
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/options/workers.md

@@ -0,0 +1,42 @@
+---
+title: Workers
+url: /options/workers
+next: middleware/
+---
+Itsi is a preforking server. It can run as either a single process (`workers 1`) or in clustered mode (`workers > 1`).
+<br/>You can switch between the two without downtime.
+
+## Configuration File
+The number of workers to use can be specified inside the configuration file (usually `./Itsi.rb` at the project root)
+using the `workers` function.
+
+## Examples
+
+```ruby {filename="Itsi.rb"}
+# Starts a single worker, putting Itsi in single-process mode
+workers 1
+```
+
+```ruby {filename="Itsi.rb"}
+# Starts 4 workers, putting Itsi in cluster-process mode
+workers 4
+```
+
+```ruby {filename="Itsi.rb"}
+# Sets the number of workers to the number of CPU cores available on the system
+workers Etc.nprocessors
+```
+
+To maximize performance, it's typical to increase number of workers
+to be at or near the number of CPU cores available on your system.
+
+However, note hyperthreads and efficiency cores may impact this and using every available core is not
+always the most effective choice.
+
+## Command Line
+You can also override the number of workers using either the `-w` or workers `--workers` command line option.
+E.g.
+
+```bash
+itsi -w 4
+```

data/lib/itsi/server/config/options/workers.rb

@@ -0,0 +1,17 @@
+module Itsi
+  class Server
+    module Config
+      class Workers < Option
+
+        insert_text "workers ${1|1,2,Etc.nprocessors|} # Number of worker processes to run"
+
+        detail "Number of worker processes to run"
+
+        schema do
+          Range(1..255)
+        end
+
+      end
+    end
+  end
+end