prusalink 0.1.0

data/lib/prusalink/digest_auth.rb

@@ -0,0 +1,80 @@
+# typed: true
+# frozen_string_literal: true
+
+require "faraday"
+require "net/http/digest_auth"
+
+module Prusalink
+  # Faraday middleware for HTTP Digest authentication, the scheme PrusaLink uses.
+  #
+  # The first request goes out unsigned. When the printer answers 401 with a Digest challenge,
+  # the middleware signs the request and sends it again. It keeps the challenge, so later
+  # requests are signed up front and only retry when the printer rotates its nonce.
+  #
+  # @example
+  #   Faraday.new("http://prusa-mk4.local") do |f|
+  #     f.use Prusalink::DigestAuth, "maker", "password"
+  #   end
+  class DigestAuth < Faraday::Middleware
+    extend T::Sig
+
+    sig { params(app: T.untyped, username: String, password: String).void }
+    def initialize(app, username, password)
+      super(app)
+      @username  = username
+      @password  = password
+      @digest    = Net::HTTP::DigestAuth.new
+      @challenge = T.let(nil, T.nilable(String))
+      @mutex     = Mutex.new
+    end
+
+    def call(env)
+      request_body = env.body
+      preflight(env) if request_body.respond_to?(:read) && @challenge.nil?
+      sign(env)
+
+      response = @app.call(env)
+      return response unless challenged?(response)
+
+      # The previous response replaced env.body, put the request body back before retrying
+      env.body = request_body
+      request_body.rewind if request_body.respond_to?(:rewind)
+      @mutex.synchronize { @challenge = response.headers["www-authenticate"] }
+      sign(env)
+
+      @app.call(env)
+    end
+
+    private
+
+    # Streams (file uploads) would be sent twice if the first attempt bounced off the challenge.
+    # A bodyless HEAD to the same URL fetches the challenge first, so the upload is signed up front.
+    def preflight(env)
+      head = env.dup
+      head.method = :head
+      head.body = nil
+      head.request_headers = Faraday::Utils::Headers.new(env.request_headers)
+      head.request_headers.delete("Content-Length")
+      head.request_headers.delete("Content-Type")
+
+      response = @app.call(head)
+      @mutex.synchronize { @challenge = response.headers["www-authenticate"] } if challenged?(response)
+    end
+
+    def challenged?(response)
+      response.status == 401 && response.headers["www-authenticate"].to_s.start_with?("Digest")
+    end
+
+    def sign(env)
+      @mutex.synchronize do
+        next if @challenge.nil?
+
+        uri          = URI(env.url.to_s)
+        uri.user     = CGI.escape(@username)
+        uri.password = CGI.escape(@password)
+
+        env.request_headers["Authorization"] = @digest.auth_header(uri, @challenge, env.method.to_s.upcase)
+      end
+    end
+  end
+end

data/lib/prusalink/exceptions.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Prusalink
+  # Prusalink exceptions
+  module Exceptions
+    # Base error.
+    class Error < StandardError; end
+    # The credentials were refused (HTTP 401/403)
+    class AuthenticationError < Error; end
+    # The request can't be processed because of invalid inputs (HTTP 400)
+    class BadRequestError < Error; end
+    # Credentials are missing from the configuration. Set them using `Prusalink.configure()`
+    class MissingCredentialsError < Error; end
+    # No client is configured for the current thread. Use `Prusalink.configure()` or `Client#use`
+    class NotConfiguredError < Error; end
+    # The resource doesn't exist (HTTP 404)
+    class NotFoundError < Error; end
+    # The printer's state doesn't allow the request, e.g. pausing an idle printer (HTTP 409)
+    class ConflictError < Error; end
+    # The uploaded media type isn't supported (HTTP 415)
+    class UnsupportedMediaTypeError < Error; end
+    # The printer encountered an unexpected condition (HTTP 500)
+    class InternalServerError < Error; end
+    # The printer doesn't implement this endpoint (HTTP 501)
+    class NotImplementedError < Error; end
+    # The printer is busy or not ready (HTTP 503)
+    class ServiceUnavailableError < Error; end
+    # Any other unexpected HTTP status
+    class UnknownError < Error; end
+    # The printer could not be reached (connection refused, host unreachable, DNS failure, ...)
+    class ConnectionError < Error; end
+    # The printer did not open the connection or respond within the configured timeouts
+    class TimeoutError < ConnectionError; end
+  end
+end

data/lib/prusalink/files/file.rb

@@ -0,0 +1,87 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  class Files
+    # A file on one of the printer's storages: a print file (G-code), a firmware file or any other file.
+    #
+    # @example
+    #   file = Prusalink::Files.get(storage: "usb", path: "benchy.gcode")
+    #   file.print_file?               # => true
+    #   file.display_name              # => "benchy_0.4n_0.2mm_PLA_MK4_1h2m.gcode"
+    #   file.meta[:"filament used [g]"] # => 15.42
+    class File
+      extend T::Sig
+      include AutoInitializable
+      include Deserializable
+
+      # @!attribute [r] name
+      #   @return [String] Short file name (8.3 format on USB drives)
+      auto_attr :name, type: String
+
+      # @!attribute [r] display_name
+      #   @return [String, nil] Long file name
+      auto_attr :display_name, type: String
+
+      # @!attribute [r] read_only
+      #   @return [Boolean] Whether the file or its storage is read-only
+      auto_attr :read_only, type: T::Boolean
+
+      # @!attribute [r] size
+      #   @return [Integer, nil] Size in bytes
+      auto_attr :size, type: Integer
+
+      # @!attribute [r] file_type
+      #   @return [String] "PRINT_FILE", "FIRMWARE" or "FILE". Renamed from the API's `type`
+      auto_attr :file_type, type: String
+
+      # @!attribute [r] m_timestamp
+      #   @return [Integer] Modification time, in seconds since the Unix epoch
+      auto_attr :m_timestamp, type: Integer
+
+      # @!attribute [r] refs
+      #   @return [Files::Refs, nil] Links to download the file and to its thumbnails
+      auto_attr :refs, type: Files::Refs
+
+      # @!attribute [r] meta
+      #   @return [Hash, nil] Metadata parsed from the file. The keys are kept as the printer sends them, some contain
+      #     spaces (e.g. `:"filament used [g]"`, `:"estimated printing time (normal mode)"`)
+      auto_attr :meta, type: Hash
+
+      # @!attribute [r] extra
+      #   @return [Hash] Any additional fields returned by the API
+      auto_attr :extra, type: Hash
+
+      auto_initialize!
+
+      deserialize_config do
+        nested :refs, Files::Refs
+        rename type: :file_type
+      end
+
+      # Whether the file can be printed (G-code, binary G-code or SL1)
+      #
+      # @return [Boolean]
+      sig { returns(T::Boolean) }
+      def print_file?
+        file_type == "PRINT_FILE"
+      end
+
+      # Whether the file is a firmware file
+      #
+      # @return [Boolean]
+      sig { returns(T::Boolean) }
+      def firmware?
+        file_type == "FIRMWARE"
+      end
+
+      # Always false, see {Files::Folder#folder?}
+      #
+      # @return [Boolean]
+      sig { returns(T::Boolean) }
+      def folder?
+        false
+      end
+    end
+  end
+end

data/lib/prusalink/files/folder.rb

@@ -0,0 +1,84 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  class Files
+    # A folder, or the root of a storage, with its content.
+    #
+    # @example
+    #   folder = Prusalink::Files.get(storage: "usb")
+    #   folder.children.select(&:print_file?).map(&:display_name) # => ["benchy.gcode"]
+    #   folder.children.select(&:folder?).map(&:name)             # => ["prints"]
+    class Folder
+      extend T::Sig
+      include AutoInitializable
+      include Deserializable
+
+      # @!attribute [r] name
+      #   @return [String] Short folder name
+      auto_attr :name, type: String
+
+      # @!attribute [r] display_name
+      #   @return [String, nil] Long folder name
+      auto_attr :display_name, type: String
+
+      # @!attribute [r] read_only
+      #   @return [Boolean] Whether the folder or its storage is read-only
+      auto_attr :read_only, type: T::Boolean
+
+      # @!attribute [r] size
+      #   @return [Integer, nil] Size in bytes. Usually absent for folders
+      auto_attr :size, type: Integer
+
+      # @!attribute [r] file_type
+      #   @return [String] Always "FOLDER". Renamed from the API's `type`
+      auto_attr :file_type, type: String
+
+      # @!attribute [r] m_timestamp
+      #   @return [Integer] Modification time, in seconds since the Unix epoch
+      auto_attr :m_timestamp, type: Integer
+
+      # @!attribute [r] children
+      #   @return [Array<Files::File, Files::Folder>, nil] The folder's content. Nested folders don't include their
+      #     own children
+      auto_attr :children, type: T.any(Files::File, Files::Folder), array: true
+
+      # @!attribute [r] extra
+      #   @return [Hash] Any additional fields returned by the API
+      auto_attr :extra, type: Hash
+
+      auto_initialize!
+
+      deserialize_config do
+        rename type: :file_type
+        transform do |data|
+          data[:children] = data[:children].map { |child| Files.build_entry(child) } if data[:children].is_a?(Array)
+        end
+      end
+
+      # Always false
+      #
+      # @return [Boolean]
+      sig { returns(T::Boolean) }
+      def print_file?
+        false
+      end
+
+      # Always false
+      #
+      # @return [Boolean]
+      sig { returns(T::Boolean) }
+      def firmware?
+        false
+      end
+
+      # Always true
+      #
+      # @return [Boolean]
+      sig { returns(T::Boolean) }
+      def folder?
+        true
+      end
+    end
+  end
+end

data/lib/prusalink/files/refs.rb

@@ -0,0 +1,36 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  class Files
+    # Links to a file's download, icon and thumbnail. The paths are relative to the printer's host.
+    #
+    # @example
+    #   file = Prusalink::Files.get(storage: "usb", path: "benchy.gcode")
+    #   file.refs.download  # => "/usb/benchy.gcode"
+    #   file.refs.thumbnail # => "/thumb/l/usb/benchy.gcode"
+    class Refs
+      extend T::Sig
+      include AutoInitializable
+      include Deserializable
+
+      # @!attribute [r] download
+      #   @return [String, nil] Path to download the file
+      auto_attr :download, type: String
+
+      # @!attribute [r] icon
+      #   @return [String, nil] Path to the file's small thumbnail. Print files only
+      auto_attr :icon, type: String
+
+      # @!attribute [r] thumbnail
+      #   @return [String, nil] Path to the file's full size thumbnail. Print files only
+      auto_attr :thumbnail, type: String
+
+      # @!attribute [r] extra
+      #   @return [Hash] Any additional fields returned by the API
+      auto_attr :extra, type: Hash
+
+      auto_initialize!
+    end
+  end
+end

data/lib/prusalink/files.rb

@@ -0,0 +1,184 @@
+# typed: true
+# frozen_string_literal: true
+
+require "erb"
+require "stringio"
+require "tempfile"
+
+module Prusalink
+  # Files and folders on the printer's storages (USB drive, local storage, SD card).
+  #
+  # `storage` is the storage's name, with or without slashes ("usb", "/usb" or "local").
+  # `path` is relative to the storage, with or without a leading slash. Spaces and other special
+  # characters are URL-encoded for you.
+  #
+  # @example
+  #   folder = Prusalink::Files.get(storage: "usb")
+  #   folder.children.map(&:display_name) # => ["benchy.gcode", "prints"]
+  #
+  #   Prusalink::Files.upload("benchy.gcode", storage: "usb", path: "prints/benchy.gcode", print_after_upload: true)
+  #   Prusalink::Files.exists?(storage: "usb", path: "prints/benchy.gcode") # => true
+  #   Prusalink::Files.delete(storage: "usb", path: "prints/benchy.gcode")
+  class Files < BaseResource
+    extend T::Sig
+
+    resource_path("/api/v1/files")
+
+    # Gets the metadata of a file, or a folder with its content.
+    #
+    # @param storage [String]   the storage's name, e.g. "usb"
+    # @param path [String]      path to the file or folder. Defaults to the storage's root
+    # @return [Files::File, Files::Folder]
+    # @raise [Prusalink::Exceptions::NotFoundError] if the file doesn't exist
+    sig { params(storage: String, path: String).returns(T.any(Files::File, Files::Folder)) }
+    def self.get(storage:, path: "")
+      build_entry(client.request(file_path(storage, path), http_method: :get))
+    end
+
+    # Uploads a file. The file is streamed, it isn't loaded in memory.
+    #
+    # @example From a path on disk
+    #   Prusalink::Files.upload("benchy.gcode", storage: "usb", path: "benchy.gcode")
+    #
+    # @example From an IO
+    #   Prusalink::Files.upload(StringIO.new(gcode), storage: "usb", path: "generated.gcode", overwrite: true)
+    #
+    # @param file [String, IO, StringIO, Tempfile]  a path to a file on disk, or an IO with a known size
+    # @param storage [String]                       the storage's name, e.g. "usb"
+    # @param path [String]                          the destination path, including the file name
+    # @param print_after_upload [Boolean]           whether to start printing the file once it is uploaded
+    # @param overwrite [Boolean]                    whether to replace an existing file
+    # @return [true]
+    # @raise [Prusalink::Exceptions::ConflictError] if the file already exists and overwrite is false
+    # @raise [ArgumentError] if the IO doesn't know its size (e.g. a pipe)
+    sig do
+      params(
+        file: T.any(String, IO, StringIO, Tempfile),
+        storage: String,
+        path: String,
+        print_after_upload: T::Boolean,
+        overwrite: T::Boolean
+      ).returns(T::Boolean)
+    end
+    def self.upload(file, storage:, path:, print_after_upload: false, overwrite: false)
+      destination = file_path(storage, path)
+      headers = {
+        "Content-Type" => "application/octet-stream",
+        "Print-After-Upload" => structured_boolean(print_after_upload),
+        "Overwrite" => structured_boolean(overwrite)
+      }
+
+      if file.is_a?(String)
+        ::File.open(file, "rb") { |io| upload_io(io, destination, headers) }
+      else
+        upload_io(file, destination, headers)
+      end
+    end
+
+    # Starts printing an existing file, if no print job is running.
+    #
+    # @param storage [String]   the storage's name, e.g. "usb"
+    # @param path [String]      path to the file
+    # @return [true]
+    # @raise [Prusalink::Exceptions::ConflictError] if the printer is busy
+    sig { params(storage: String, path: String).returns(T::Boolean) }
+    def self.print(storage:, path:)
+      post(path: file_path(storage, path))
+    end
+
+    # Deletes a file or a folder.
+    #
+    # Replaces {BaseResource.delete} with a signature that fits files, then calls it with the built path and
+    # headers. The signatures differ on purpose, hence `allow_incompatible`.
+    #
+    # @param storage [String]   the storage's name, e.g. "usb"
+    # @param path [String]      path to the file or folder
+    # @param force [Boolean]    whether to delete a folder that isn't empty
+    # @return [true]
+    # @raise [Prusalink::Exceptions::ConflictError] if the file is being printed, or the folder isn't empty
+    sig do
+      override(allow_incompatible: true)
+        .params(storage: String, path: String, force: T::Boolean)
+        .returns(T::Boolean)
+    end
+    def self.delete(storage:, path:, force: false)
+      super(path: file_path(storage, path), headers: { "Force" => structured_boolean(force) })
+    end
+
+    # Whether a file or folder exists.
+    #
+    # @param storage [String]   the storage's name, e.g. "usb"
+    # @param path [String]      path to the file or folder
+    # @return [Boolean]
+    sig { params(storage: String, path: String).returns(T::Boolean) }
+    def self.exists?(storage:, path:)
+      head(path: file_path(storage, path))
+      true
+    rescue Exceptions::NotFoundError
+      false
+    end
+
+    # Whether a file is read-only, and whether it is being printed.
+    #
+    # @example
+    #   Prusalink::Files.info(storage: "usb", path: "benchy.gcode")
+    #   # => { read_only: false, currently_printed: true }
+    #
+    # @param storage [String]   the storage's name, e.g. "usb"
+    # @param path [String]      path to the file or folder
+    # @return [Hash{Symbol => Boolean}]
+    # @raise [Prusalink::Exceptions::NotFoundError] if the file doesn't exist
+    sig { params(storage: String, path: String).returns(T::Hash[Symbol, T::Boolean]) }
+    def self.info(storage:, path:)
+      headers = head(path: file_path(storage, path))
+
+      {
+        read_only: header_true?(headers["read-only"]),
+        currently_printed: header_true?(headers["currently-printed"])
+      }
+    end
+
+    # Builds a {Files::Folder} or a {Files::File} according to the entry's `type`.
+    #
+    # @param data [Hash] a file or folder, as returned by the API
+    # @return [Files::File, Files::Folder]
+    # @api private
+    sig { params(data: T::Hash[Symbol, T.untyped]).returns(T.any(Files::File, Files::Folder)) }
+    def self.build_entry(data)
+      data[:type] == "FOLDER" ? Files::Folder.deserialize(data) : Files::File.deserialize(data)
+    end
+
+    # Builds the request path, e.g. ("/usb/", "/my prints/benchy (1).gcode")
+    # gives "/api/v1/files/usb/my%20prints/benchy%20%281%29.gcode".
+    # Every segment is URL-encoded (spaces as %20, parentheses as %28 and %29), slashes are kept.
+    sig { params(storage: String, path: String).returns(String) }
+    private_class_method def self.file_path(storage, path)
+      segments = [storage, path].flat_map { |part| part.split("/") }.reject(&:empty?)
+
+      [@path, *segments.map { |segment| ERB::Util.url_encode(segment) }].join("/")
+    end
+
+    sig { params(io: T.any(IO, StringIO, Tempfile), path: String, headers: T::Hash[String, String]).returns(T::Boolean) }
+    private_class_method def self.upload_io(io, path, headers)
+      # PrusaLink requires a Content-Length, so the IO must know its size (File, StringIO, Tempfile).
+      # A pipe or a socket doesn't.
+      unless io.respond_to?(:size)
+        raise ArgumentError, "Can't upload a #{io.class} without a known size. Pass a path, a File or a StringIO"
+      end
+
+      put(path: path, params: io, headers: headers.merge("Content-Length" => T.unsafe(io).size.to_s))
+    end
+
+    # RFC 8941 boolean, the format PrusaLink expects in its headers
+    sig { params(value: T::Boolean).returns(String) }
+    private_class_method def self.structured_boolean(value)
+      value ? "?1" : "?0"
+    end
+
+    # PrusaLink sends booleans in headers as "true"/"false" or as RFC 8941 booleans ("?1"/"?0")
+    sig { params(value: T.nilable(String)).returns(T::Boolean) }
+    private_class_method def self.header_true?(value)
+      %w[true ?1 1].include?(value.to_s.strip.downcase)
+    end
+  end
+end

data/lib/prusalink/info.rb

@@ -0,0 +1,82 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  # General information about the printer: its name, location, serial number and hardware setup.
+  #
+  # @example
+  #   info = Prusalink::Info.get
+  #   info.name            # => "MuadDib"
+  #   info.nozzle_diameter # => 0.4
+  #   info.mmu             # => false
+  class Info < BaseResource
+    extend T::Sig
+    include AutoInitializable
+    include Deserializable
+
+    resource_path("/api/v1/info")
+
+    # @!attribute [r] mmu
+    #   @return [Boolean] Whether a Multi Material Unit is attached
+    auto_attr :mmu, type: T::Boolean
+
+    # @!attribute [r] name
+    #   @return [String] The printer's name, as set by the user
+    auto_attr :name, type: String
+
+    # @!attribute [r] location
+    #   @return [String] The printer's location, as set by the user
+    auto_attr :location, type: String
+
+    # @!attribute [r] farm_mode
+    #   @return [Boolean] Whether the printer runs in farm mode
+    auto_attr :farm_mode, type: T::Boolean
+
+    # @!attribute [r] nozzle_diameter
+    #   @return [Float] The nozzle diameter, in millimeters
+    auto_attr :nozzle_diameter, type: Float
+
+    # @!attribute [r] min_extrusion_temp
+    #   @return [Integer] The minimum nozzle temperature allowing extrusion, in °C
+    auto_attr :min_extrusion_temp, type: Integer
+
+    # @!attribute [r] serial
+    #   @return [String] The printer's serial number
+    auto_attr :serial, type: String
+
+    # @!attribute [r] sd_ready
+    #   @return [Boolean] Whether an SD card is inserted and ready
+    auto_attr :sd_ready, type: T::Boolean
+
+    # @!attribute [r] active_camera
+    #   @return [Boolean] Whether a camera is active
+    auto_attr :active_camera, type: T::Boolean
+
+    # @!attribute [r] hostname
+    #   @return [String] The printer's network hostname
+    auto_attr :hostname, type: String
+
+    # @!attribute [r] port
+    #   @return [String] The serial port the printer is connected to, e.g. "/dev/tty"
+    auto_attr :port, type: String
+
+    # @!attribute [r] network_error_chime
+    #   @return [Boolean] Whether the printer chimes on network errors
+    auto_attr :network_error_chime, type: T::Boolean
+
+    # @!attribute [r] extra
+    #   @return [Hash] Any additional fields returned by the API
+    auto_attr :extra, type: Hash
+
+    auto_initialize!
+
+    # Retrieve general information about the printer.
+    #
+    # @return [Info, nil] nil when the printer answers 204 No Content
+    # @raise [Prusalink::Exceptions::Error] if the request fails
+    sig { returns(T.nilable(Info)) }
+    def self.get
+      fetch_resource
+    end
+  end
+end

data/lib/prusalink/job/file.rb

@@ -0,0 +1,70 @@
+# typed: true
+# frozen_string_literal: true
+
+module Prusalink
+  class Job
+    # The file being printed by the current job.
+    #
+    # @example
+    #   file = Prusalink::Job.get.file
+    #   file.display_name # => "Spice_Harvester_0.3mm_PLA_MK3S_12m.gcode"
+    #   file.full_path    # => "/usb/SPICE~1.gco"
+    class File
+      extend T::Sig
+      include AutoInitializable
+      include Deserializable
+
+      # @!attribute [r] name
+      #   @return [String] Short filename, e.g. "SPICE~1.gco"
+      auto_attr :name, type: String
+
+      # @!attribute [r] display_name
+      #   @return [String, nil] Long filename, e.g. "Spice_Harvester_0.3mm_PLA_MK3S_12m.gcode"
+      auto_attr :display_name, type: String
+
+      # @!attribute [r] path
+      #   @return [String] Path of the folder containing the file, e.g. "/local"
+      auto_attr :path, type: String
+
+      # @!attribute [r] display_path
+      #   @return [String, nil] Human readable path of the folder, e.g. "/PrusaLink gcodes"
+      auto_attr :display_path, type: String
+
+      # @!attribute [r] size
+      #   @return [Integer, nil] File size in bytes
+      auto_attr :size, type: Integer
+
+      # @!attribute [r] m_timestamp
+      #   @return [Integer] Modification time, in seconds since the epoch
+      auto_attr :m_timestamp, type: Integer
+
+      # @!attribute [r] meta
+      #   @return [Hash, nil] Metadata parsed from the G-code. Keys are symbols and may contain spaces,
+      #     e.g. :"filament used [g]"
+      auto_attr :meta, type: Hash
+
+      # @!attribute [r] refs
+      #   @return [Hash, nil] Links to the file's download, icon and thumbnail, e.g. { download: "/api/files/..." }
+      auto_attr :refs, type: Hash
+
+      # @!attribute [r] extra
+      #   @return [Hash] Any additional fields returned by the API
+      auto_attr :extra, type: Hash
+
+      auto_initialize!
+
+      # The complete path of the file on the printer, joining {#path} and {#name}.
+      #
+      # @example
+      #   file.path      # => "/usb"
+      #   file.name      # => "SPICE~1.gco"
+      #   file.full_path # => "/usb/SPICE~1.gco"
+      #
+      # @return [String]
+      sig { returns(String) }
+      def full_path
+        [path.to_s.chomp("/"), name].join("/")
+      end
+    end
+  end
+end