sillydev 1.0.0

data/lib/sillydev/envelope.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module SillyDev
+  # Removing the panel's {"object", "attributes"} envelopes.
+  module Envelope
+    ITEM_KEYS = %w[object attributes meta].freeze
+    LIST_KEYS = %w[object data meta].freeze
+
+    module_function
+
+    # Strips the envelopes from an API response, at every level.
+    #
+    # {"object" => "server", "attributes" => {...}} becomes the attributes,
+    # {"object" => "list", "data" => [...]} becomes the list of items, a map such as
+    # {"object" => "server_stats_list", "data" => {uuid => item}} becomes {uuid => attributes},
+    # and a null_resource (a relationship the key may not see) becomes nil.
+    def unwrap(value)
+      case value
+      when Array
+        value.map { |item| unwrap(item) }
+      when Hash
+        kind = value["object"]
+        if kind.is_a?(String)
+          return nil if kind == "null_resource"
+          return unwrap(value["attributes"]) if value.key?("attributes") && (value.keys - ITEM_KEYS).empty?
+          if value.key?("data") && (value.keys - LIST_KEYS).empty? && (value["data"].is_a?(Array) || value["data"].is_a?(Hash))
+            return unwrap(value["data"])
+          end
+        end
+        value.to_h { |key, item| [key, unwrap(item)] }
+      else
+        value
+      end
+    end
+  end
+
+  # One page of a paginated list: the unwrapped items plus the list's meta.
+  class Page
+    include Enumerable
+
+    attr_reader :data, :meta
+
+    def self.from_response(body)
+      return new([], {}) unless body.is_a?(Hash)
+
+      meta = body["meta"].is_a?(Hash) ? Envelope.unwrap(body["meta"]) : {}
+      new(Array(Envelope.unwrap(body["data"] || [])), meta)
+    end
+
+    def initialize(data, meta = {})
+      @data = data
+      @meta = meta
+    end
+
+    def pagination
+      meta["pagination"].is_a?(Hash) ? meta["pagination"] : {}
+    end
+
+    def current_page
+      (pagination["current_page"] || 1).to_i
+    end
+
+    def total_pages
+      (pagination["total_pages"] || 1).to_i
+    end
+
+    def total
+      pagination["total"]&.to_i
+    end
+
+    def next_page?
+      !data.empty? && current_page < total_pages
+    end
+
+    def each(&)
+      data.each(&)
+    end
+
+    def size
+      data.size
+    end
+    alias length size
+  end
+end

data/lib/sillydev/errors.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SillyDev
+  # Base class for every error this gem raises.
+  #
+  # Errors the API answers with come as {"errors": [{"code", "status", "detail"}]}: the message is
+  # the first detail and #errors holds the whole list.
+  class Error < StandardError
+    attr_reader :status_code, :errors, :response
+
+    def initialize(message = nil, status_code: nil, errors: nil, response: nil)
+      super(message)
+      @status_code = status_code
+      @errors = errors || []
+      @response = response
+    end
+
+    # The code of the first error, such as "NotFoundHttpException".
+    def code
+      first = @errors.first
+      first && !first["code"].nil? ? first["code"].to_s : nil
+    end
+  end
+
+  # The API could not be reached (DNS, TLS, connection refused or a timeout).
+  class APIConnectionError < Error; end
+
+  # The API answered with an error status that has no more specific class.
+  class APIStatusError < Error; end
+
+  # 400: the request could not be carried out as sent.
+  class BadRequestError < APIStatusError; end
+
+  # 401: no API key, or it is wrong, expired or deleted.
+  class AuthenticationError < APIStatusError; end
+
+  # 403: the key is valid but may not do this.
+  class PermissionDeniedError < APIStatusError; end
+
+  # 404: no such resource, the key cannot see it, or the feature is switched off.
+  class NotFoundError < APIStatusError; end
+
+  # 409: the resource is busy or in a state that does not allow this right now.
+  class ConflictError < APIStatusError; end
+
+  # 422: some fields were missing or invalid. #errors has one entry per problem.
+  class ValidationError < APIStatusError
+    # The details grouped by the field they are about (meta.source_field).
+    def fields
+      errors.each_with_object({}) do |error, out|
+        meta = error["meta"].is_a?(Hash) ? error["meta"] : {}
+        (out[meta["source_field"].to_s] ||= []) << error["detail"].to_s
+      end
+    end
+  end
+
+  # 429: too many requests. #retry_after is the number of seconds to wait, if sent.
+  class RateLimitError < APIStatusError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  # 5xx: something went wrong on the panel or on the node running the server.
+  class ServerError < APIStatusError; end
+
+  # A wait such as servers.wait_for_state ran out of time. #state is the server's state when it
+  # gave up.
+  class WaitTimeoutError < Error
+    attr_reader :state
+
+    def initialize(message = nil, state: nil)
+      super(message)
+      @state = state
+    end
+  end
+
+  # A console connection could not be opened, or it ended.
+  #
+  # #reason says why: "suspended" (the server is suspended; connecting again won't help),
+  # "booting" (the node is still loading the server; try again in a few seconds), "token" (the
+  # node refused the token), "timeout", "network" (the node or the panel could not be reached, or
+  # the connection dropped), "deleted" (the server has been deleted), "throttled" (messages were
+  # sent faster than the node takes them) or "unavailable" (this way of connecting isn't
+  # available here). #transport is the way that failed, and with transport "auto", #attempts holds
+  # why each way tried failed.
+  class ConsoleError < Error
+    attr_reader :reason, :transport, :attempts
+
+    def initialize(message = nil, reason = "network", transport: nil, attempts: nil)
+      super(message)
+      @reason = reason
+      @transport = transport
+      @attempts = attempts || []
+    end
+  end
+
+  # Turning error responses into exceptions.
+  module Errors
+    BY_STATUS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => ValidationError,
+    }.freeze
+
+    module_function
+
+    # Seconds from a Retry-After header, or nil when it is missing or not a number.
+    def parse_retry_after(value)
+      return nil if value.nil?
+
+      seconds = Float(value.to_s.strip)
+      seconds.negative? ? 0.0 : seconds
+    rescue ArgumentError
+      nil
+    end
+
+    # The exception that matches an error response.
+    def for_response(response)
+      status = response.status
+      body = begin
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+      errors = []
+      if body.is_a?(Hash)
+        if body["errors"].is_a?(Array)
+          errors = body["errors"].grep(Hash)
+        elsif body["error"].is_a?(String)
+          # The node (Wings) answers signed-URL requests in its own format.
+          error = { "code" => "NodeError", "status" => status.to_s, "detail" => body["error"] }
+          # The console relay passes the node's refusals on in the same format.
+          meta = body.slice("booting", "suspended", "jwt").select { |_, v| [true, false].include?(v) }
+          error["meta"] = meta unless meta.empty?
+          errors = [error]
+        elsif body["message"].is_a?(String)
+          errors = [{ "code" => "HttpException", "status" => status.to_s, "detail" => body["message"] }]
+        end
+      end
+      message = errors.empty? ? "" : (errors.first["detail"] || errors.first["code"]).to_s
+      message = "HTTP error" if message.empty?
+      message = "#{status}: #{message}"
+
+      kwargs = { status_code: status, errors: errors, response: response }
+      return RateLimitError.new(message, retry_after: parse_retry_after(response.header("retry-after")), **kwargs) if status == 429
+
+      klass = BY_STATUS[status] || (status >= 500 ? ServerError : APIStatusError)
+      klass.new(message, **kwargs)
+    end
+  end
+end

data/lib/sillydev/mcp_server.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../sillydev"
+
+module SillyDev
+  # An MCP server that lets AI assistants look after your Silly Development servers.
+  #
+  # Run it with `sillydev mcp`. It speaks MCP (JSON-RPC 2.0, one message per line) over stdio and
+  # reads the API key from SILLYDEV_API_KEY. Give it a key limited to the servers and permissions
+  # you want the assistant to have.
+  #
+  # The tools are deliberately few: list servers, read a server's status, power actions, console
+  # commands, reading recent console output, list and read files, Git deploys and listing backups.
+  # There is nothing that spends money, deletes anything or changes who can reach a server.
+  class MCPServer
+    PROTOCOL_VERSIONS = %w[2025-06-18 2025-03-26 2024-11-05].freeze
+
+    # read_file returns at most this many characters, so one large log cannot swamp the context.
+    MAX_FILE_CHARS = 100_000
+
+    INSTRUCTIONS = "Tools for the user's Silly Development servers (Discord bots and other apps). " \
+                   "Servers are named by their 8-character identifier, which list_servers returns. " \
+                   "Power actions and console commands affect a live server: say what you are about to do first."
+
+    SERVER = { "server" => { "type" => "string", "description" => "The server's 8-character identifier or UUID." } }.freeze
+
+    def self.schema(properties = {}, required = [])
+      { "type" => "object", "properties" => properties, "required" => required }
+    end
+
+    TOOLS = [
+      ["list_servers", "List the servers this API key can reach, with their identifiers, names and limits.", schema],
+      ["server_status",
+       "Get a server's live state (offline, starting, running, stopping) and its CPU, memory, disk and network use.",
+       schema(SERVER, ["server"])],
+      ["power_action", "Start, stop, restart or kill a server. signal is one of start, stop, restart, kill.",
+       schema(SERVER.merge("signal" => { "type" => "string", "enum" => %w[start stop restart kill] }), %w[server signal])],
+      ["send_command", "Send a command to a server's console, as if typed into it.",
+       schema(SERVER.merge("command" => { "type" => "string" }), %w[server command])],
+      ["read_console",
+       "Read a server's recent console output (about the last 150 lines), oldest first. lines limits it to the " \
+       "latest lines. Empty while the server is offline.",
+       schema(SERVER.merge("lines" => { "type" => "integer", "default" => 100 }), ["server"])],
+      ["list_files", "List the files and folders in one directory of a server. directory defaults to /.",
+       schema(SERVER.merge("directory" => { "type" => "string", "default" => "/" }), ["server"])],
+      ["read_file", "Read a text file from a server, such as a config file or a log.",
+       schema(SERVER.merge("path" => { "type" => "string" }), %w[server path])],
+      ["git_deploy", "Deploy the Git repository linked to a server now. Returns the queued deployment.",
+       schema(SERVER, ["server"])],
+      ["list_backups", "List a server's backups: name, size, whether it finished and succeeded, and when.",
+       schema(SERVER, ["server"])],
+    ].map { |name, description, input| { "name" => name, "description" => description, "inputSchema" => input } }.freeze
+
+    TOOL_NAMES = TOOLS.map { |tool| tool["name"] }.freeze
+
+    def self.main(api_key: nil, base_url: nil, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      client = Client.new(api_key, base_url: base_url)
+      new(client).serve(stdin, stdout)
+      0
+    rescue Error => e
+      stderr.puts("sillydev mcp: #{e.message}")
+      1
+    end
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Answers messages from input, one JSON-RPC message per line, until it ends.
+    def serve(input, output)
+      output.sync = true if output.respond_to?(:sync=)
+      input.each_line do |line|
+        next if line.strip.empty?
+
+        reply = handle_line(line)
+        output.puts(JSON.generate(reply)) if reply
+      end
+    end
+
+    # The answer to one line (a message or a batch), or nil for notifications.
+    def handle_line(line)
+      message = JSON.parse(line)
+      if message.is_a?(Array)
+        replies = message.filter_map { |m| handle(m) }
+        return replies.empty? ? nil : replies
+      end
+      handle(message)
+    rescue JSON::ParserError
+      error_reply(nil, -32_700, "Parse error")
+    end
+
+    def handle(message)
+      return error_reply(nil, -32_600, "Invalid Request") unless message.is_a?(Hash)
+
+      id = message["id"]
+      method = message["method"]
+      return nil if method.nil? || (!message.key?("id") && method.start_with?("notifications/"))
+      return nil unless message.key?("id")
+
+      result = case method
+               when "initialize" then initialize_result(message["params"] || {})
+               when "ping" then {}
+               when "tools/list" then { "tools" => TOOLS }
+               when "tools/call" then call_tool(message["params"] || {})
+               else return error_reply(id, -32_601, "Method not found: #{method}")
+               end
+      { "jsonrpc" => "2.0", "id" => id, "result" => result }
+    rescue ArgumentError => e
+      error_reply(id, -32_602, e.message)
+    end
+
+    # Runs one tool. Errors from the API come back as a tool result with isError, so the
+    # assistant can read them.
+    def call_tool(params)
+      name = params["name"]
+      args = params["arguments"].is_a?(Hash) ? params["arguments"] : {}
+      raise ArgumentError, "Unknown tool: #{name}" unless TOOL_NAMES.include?(name)
+
+      value = run_tool(name, args)
+      text = value.is_a?(String) ? value : JSON.pretty_generate(value)
+      { "content" => [{ "type" => "text", "text" => text }], "isError" => false }
+    rescue Error, ToolError => e
+      { "content" => [{ "type" => "text", "text" => e.message }], "isError" => true }
+    end
+
+    private
+
+    class ToolError < StandardError; end
+
+    def initialize_result(params)
+      asked = params["protocolVersion"]
+      {
+        "protocolVersion" => PROTOCOL_VERSIONS.include?(asked) ? asked : PROTOCOL_VERSIONS.first,
+        "capabilities" => { "tools" => { "listChanged" => false } },
+        "serverInfo" => { "name" => "sillydev", "version" => VERSION },
+        "instructions" => INSTRUCTIONS,
+      }
+    end
+
+    def arg(args, name)
+      value = args[name]
+      raise ToolError, "#{name} is required" if value.nil? || value.to_s.empty?
+
+      value.to_s
+    end
+
+    def run_tool(name, args)
+      panel = @client.panel
+      case name
+      when "list_servers"
+        keys = %w[identifier uuid name description node limits is_suspended is_installing is_paid]
+        panel.servers.list.map { |s| s.slice(*keys) }
+      when "server_status" then panel.servers.resources(arg(args, "server"))
+      when "power_action"
+        server = arg(args, "server")
+        signal = arg(args, "signal")
+        raise ToolError, "signal must be start, stop, restart or kill" unless %w[start stop restart kill].include?(signal)
+
+        panel.servers.power(server, signal)
+        "Sent #{signal} to #{server}."
+      when "send_command"
+        server = arg(args, "server")
+        command = arg(args, "command")
+        panel.servers.command(server, command)
+        "Sent to #{server}: #{command}"
+      when "read_console" then read_console(arg(args, "server"), args["lines"])
+      when "list_files"
+        files = panel.files.list(arg(args, "server"), (args["directory"] || "/").to_s)
+        files.map { |f| f.slice("name", "is_file", "size", "mimetype", "modified_at") }
+      when "read_file"
+        text = panel.files.read(arg(args, "server"), arg(args, "path"))
+        return text if text.length <= MAX_FILE_CHARS
+
+        "#{text[-MAX_FILE_CHARS..]}\n[showing the last #{MAX_FILE_CHARS} characters of #{text.length}]"
+      when "git_deploy" then panel.git.deploy(arg(args, "server"))
+      when "list_backups" then panel.backups.list(arg(args, "server")).to_a
+      end
+    end
+
+    def read_console(server, lines)
+      history = @client.panel.console.history(server)
+      return "#{server} has no console output: it is offline, or has printed nothing since it started." if history.empty?
+
+      count = [Integer(lines || 100, exception: false) || 100, 1].max
+      history.last(count).join("\n")[-MAX_FILE_CHARS..] || history.last(count).join("\n")
+    end
+
+    def error_reply(id, code, message)
+      { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => code, "message" => message } }
+    end
+  end
+end

data/lib/sillydev/monitoring/aggregator.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module SillyDev
+  module Monitoring
+    # Seconds per aggregation window. Each series sends at most one point per window.
+    WINDOW = 10
+
+    # Upper bounds (ms) of the first 15 histogram buckets; the 16th is everything above 60000.
+    BOUNDS = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10_000, 30_000, 60_000].freeze
+    BUCKETS = BOUNDS.length + 1
+
+    # Client-side pre-aggregation of metrics into fixed windows (see feathers/docs/ingest.md). Holds
+    # one value per (window, name, type, tags). Not thread-safe: the client locks around it.
+    class Aggregator
+      Histogram = Struct.new(:count, :sum, :min, :max, :buckets) do # rubocop:disable Lint/StructNewOverride
+        def add(value)
+          self.count += 1
+          self.sum += value
+          self.min = value if value < min
+          self.max = value if value > max
+          buckets[Aggregator.bucket_index(value)] += 1
+        end
+      end
+
+      # The first bucket whose upper bound is >= value (the 16th for anything above 60000).
+      def self.bucket_index(value)
+        BOUNDS.bsearch_index { |bound| bound >= value } || BOUNDS.length
+      end
+
+      attr_accessor :dropped
+      attr_reader :max_series
+
+      def initialize(max_series = 2000)
+        @max_series = max_series
+        @series = {}
+        @dropped = 0
+      end
+
+      def size
+        @series.size
+      end
+
+      def counter(ts, name, value, tags)
+        key = slot(ts, name, "counter", tags)
+        @series[key] = (@series[key] || 0) + value if key
+      end
+
+      def gauge(ts, name, value, tags)
+        key = slot(ts, name, "gauge", tags)
+        @series[key] = value if key
+      end
+
+      def histogram(ts, name, value, tags)
+        key = slot(ts, name, "histogram", tags)
+        return unless key
+
+        hist = @series[key]
+        hist = @series[key] = Histogram.new(0, 0.0, Float::INFINITY, -Float::INFINITY, Array.new(BUCKETS, 0)) unless hist.is_a?(Histogram)
+        hist.add(value)
+      end
+
+      # Removes and returns the points of every window that has ended by now (all when nil).
+      def drain(now = nil)
+        cutoff = now.nil? ? nil : (now.to_f / WINDOW).floor * WINDOW
+        out = []
+        @series.keys.sort_by(&:first).each do |key|
+          start, name, kind, tags = key
+          next if cutoff && start >= cutoff
+
+          value = @series.delete(key)
+          item = { "name" => name, "type" => kind, "ts" => start }
+          if kind == "histogram"
+            item.merge!("count" => value.count, "sum" => num(value.sum), "min" => num(value.min),
+                        "max" => num(value.max), "buckets" => value.buckets.dup)
+          else
+            item["value"] = num(value)
+          end
+          item["tags"] = tags.to_h unless tags.empty?
+          out << item
+        end
+        out
+      end
+
+      def clear
+        @series.clear
+      end
+
+      private
+
+      def slot(ts, name, kind, tags)
+        key = [(ts.to_f / WINDOW).floor * WINDOW, name, kind, tags]
+        if !@series.key?(key) && @series.size >= @max_series
+          @dropped += 1
+          return nil
+        end
+        key
+      end
+
+      def num(value)
+        return value.to_i if value.is_a?(Float) && value.finite? && value == value.floor
+        return value.round(6) if value.is_a?(Float)
+
+        value
+      end
+    end
+  end
+end