octoprint 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +10 -0
  3. data/LICENSE.txt +21 -0
  4. data/README.md +336 -0
  5. data/lib/octoprint/access/group.rb +88 -0
  6. data/lib/octoprint/access/groups.rb +166 -0
  7. data/lib/octoprint/access/login_response.rb +63 -0
  8. data/lib/octoprint/access/permission.rb +71 -0
  9. data/lib/octoprint/access/permissions.rb +29 -0
  10. data/lib/octoprint/access/user.rb +95 -0
  11. data/lib/octoprint/access/users.rb +347 -0
  12. data/lib/octoprint/auto_initializable.rb +219 -0
  13. data/lib/octoprint/base_resource.rb +139 -0
  14. data/lib/octoprint/client.rb +151 -0
  15. data/lib/octoprint/connection/options.rb +44 -0
  16. data/lib/octoprint/connection/settings.rb +35 -0
  17. data/lib/octoprint/connection.rb +74 -0
  18. data/lib/octoprint/deserializable.rb +483 -0
  19. data/lib/octoprint/exceptions.rb +30 -0
  20. data/lib/octoprint/files/file.rb +55 -0
  21. data/lib/octoprint/files/folder.rb +29 -0
  22. data/lib/octoprint/files/operation_result.rb +37 -0
  23. data/lib/octoprint/files/refs.rb +19 -0
  24. data/lib/octoprint/files.rb +238 -0
  25. data/lib/octoprint/job/information.rb +42 -0
  26. data/lib/octoprint/job/progress.rb +46 -0
  27. data/lib/octoprint/job.rb +140 -0
  28. data/lib/octoprint/languages/language_pack.rb +31 -0
  29. data/lib/octoprint/languages.rb +102 -0
  30. data/lib/octoprint/location.rb +23 -0
  31. data/lib/octoprint/logs/log_file.rb +59 -0
  32. data/lib/octoprint/logs/references.rb +28 -0
  33. data/lib/octoprint/logs.rb +98 -0
  34. data/lib/octoprint/printer/bed.rb +32 -0
  35. data/lib/octoprint/printer/chamber.rb +29 -0
  36. data/lib/octoprint/printer/command.rb +129 -0
  37. data/lib/octoprint/printer/custom_control/input.rb +45 -0
  38. data/lib/octoprint/printer/custom_control.rb +119 -0
  39. data/lib/octoprint/printer/error_information.rb +104 -0
  40. data/lib/octoprint/printer/heater.rb +113 -0
  41. data/lib/octoprint/printer/history_query.rb +25 -0
  42. data/lib/octoprint/printer/printhead.rb +105 -0
  43. data/lib/octoprint/printer/sd.rb +97 -0
  44. data/lib/octoprint/printer/state.rb +41 -0
  45. data/lib/octoprint/printer/state_flags.rb +70 -0
  46. data/lib/octoprint/printer/temperature_attributes.rb +70 -0
  47. data/lib/octoprint/printer/temperature_data.rb +53 -0
  48. data/lib/octoprint/printer/temperature_data_point.rb +73 -0
  49. data/lib/octoprint/printer/temperature_reading.rb +47 -0
  50. data/lib/octoprint/printer/temperature_state.rb +67 -0
  51. data/lib/octoprint/printer/tool.rb +154 -0
  52. data/lib/octoprint/printer.rb +126 -0
  53. data/lib/octoprint/printer_profiles/printer_profile.rb +40 -0
  54. data/lib/octoprint/printer_profiles.rb +158 -0
  55. data/lib/octoprint/server_information.rb +51 -0
  56. data/lib/octoprint/server_version.rb +52 -0
  57. data/lib/octoprint/settings/webcam.rb +135 -0
  58. data/lib/octoprint/settings.rb +133 -0
  59. data/lib/octoprint/slicing/profile.rb +65 -0
  60. data/lib/octoprint/slicing/slicer.rb +83 -0
  61. data/lib/octoprint/slicing.rb +227 -0
  62. data/lib/octoprint/system_commands/command.rb +41 -0
  63. data/lib/octoprint/system_commands.rb +110 -0
  64. data/lib/octoprint/timelapse/config.rb +68 -0
  65. data/lib/octoprint/timelapse/file_attributes.rb +50 -0
  66. data/lib/octoprint/timelapse/rendered.rb +51 -0
  67. data/lib/octoprint/timelapse/unrendered.rb +43 -0
  68. data/lib/octoprint/timelapse.rb +221 -0
  69. data/lib/octoprint/types.rb +140 -0
  70. data/lib/octoprint/util.rb +151 -0
  71. data/lib/octoprint/version.rb +7 -0
  72. data/lib/octoprint/wizard.rb +57 -0
  73. data/lib/octoprint.rb +57 -0
  74. data/rbi/octoprint/access/group.rbi +46 -0
  75. data/rbi/octoprint/access/login_response.rbi +22 -0
  76. data/rbi/octoprint/access/permission.rbi +34 -0
  77. data/rbi/octoprint/access/user.rbi +43 -0
  78. data/rbi/octoprint/connection/options.rbi +28 -0
  79. data/rbi/octoprint/connection/settings.rbi +19 -0
  80. data/rbi/octoprint/connection.rbi +13 -0
  81. data/rbi/octoprint/files/file.rbi +61 -0
  82. data/rbi/octoprint/files/folder.rbi +22 -0
  83. data/rbi/octoprint/files/operation_result.rbi +22 -0
  84. data/rbi/octoprint/files/refs.rbi +16 -0
  85. data/rbi/octoprint/job/information.rbi +22 -0
  86. data/rbi/octoprint/job/progress.rbi +25 -0
  87. data/rbi/octoprint/job.rbi +22 -0
  88. data/rbi/octoprint/languages/language_pack.rbi +19 -0
  89. data/rbi/octoprint/languages.rbi +13 -0
  90. data/rbi/octoprint/logs/log_file.rbi +19 -0
  91. data/rbi/octoprint/logs/references.rbi +13 -0
  92. data/rbi/octoprint/logs.rbi +13 -0
  93. data/rbi/octoprint/printer/bed.rbi +22 -0
  94. data/rbi/octoprint/printer/chamber.rbi +22 -0
  95. data/rbi/octoprint/printer/custom_control/input.rbi +22 -0
  96. data/rbi/octoprint/printer/custom_control.rbi +67 -0
  97. data/rbi/octoprint/printer/error_information.rbi +25 -0
  98. data/rbi/octoprint/printer/sd.rbi +13 -0
  99. data/rbi/octoprint/printer/state.rbi +19 -0
  100. data/rbi/octoprint/printer/state_flags.rbi +43 -0
  101. data/rbi/octoprint/printer/temperature_data.rbi +19 -0
  102. data/rbi/octoprint/printer/temperature_data_point.rbi +22 -0
  103. data/rbi/octoprint/printer/temperature_reading.rbi +19 -0
  104. data/rbi/octoprint/printer/temperature_state.rbi +22 -0
  105. data/rbi/octoprint/printer/tool.rbi +22 -0
  106. data/rbi/octoprint/printer.rbi +19 -0
  107. data/rbi/octoprint/printer_profiles/printer_profile.rbi +46 -0
  108. data/rbi/octoprint/printer_profiles.rbi +13 -0
  109. data/rbi/octoprint/server_information.rbi +16 -0
  110. data/rbi/octoprint/server_version.rbi +19 -0
  111. data/rbi/octoprint/settings/webcam.rbi +34 -0
  112. data/rbi/octoprint/slicing/profile.rbi +28 -0
  113. data/rbi/octoprint/slicing/slicer.rbi +31 -0
  114. data/rbi/octoprint/system_commands/command.rbi +25 -0
  115. data/rbi/octoprint/system_commands.rbi +16 -0
  116. data/rbi/octoprint/timelapse/config.rbi +31 -0
  117. data/rbi/octoprint/timelapse/rendered.rbi +31 -0
  118. data/rbi/octoprint/timelapse/unrendered.rbi +34 -0
  119. data/rbi/octoprint/timelapse.rbi +22 -0
  120. data/rbi/octoprint/util.rbi +19 -0
  121. data/rbi/octoprint.rbi +1848 -0
  122. metadata +264 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: efa119d7141723cc687ef08453f3a08a63405cdb430643e559b534b3814f8581
4
+ data.tar.gz: ffd09457f9fe90388c482344f10f0d942cdeabbfb3eeb1a69be2d45a4694e1fb
5
+ SHA512:
6
+ metadata.gz: 211b451d8d658cfaa87a2cf7df4f9b86086b591ce775a724f700bd9969d3fe350dfd2e36713ba15aa529a46086cbf7d757360a3c4554cc3e0338550d13866cdf
7
+ data.tar.gz: 0fce126469f4ee9f9d0a73ebf08c2491e6b45c8600ee48237110a20f88f4a97b56911ef3522f25ab9efba125ef8442ae70f142de59636391265c435eedc0753a
data/CHANGELOG.md ADDED
@@ -0,0 +1,10 @@
1
+ ## [Unreleased]
2
+
3
+ ## [0.1.0] - 2026-11-16
4
+
5
+ Initial release. Targets OctoPrint 1.11.x and Ruby 3.3+.
6
+
7
+ - Covers the OctoPrint REST API: files, job, printer, printer profiles, slicing, connection, languages, logs, timelapse, access control (users, groups, permissions, login/logout), settings, system commands, wizard, util, and server version/information.
8
+ - Supports one global client or several clients for multiple printers, with configurable timeouts.
9
+ - Maps HTTP errors to specific exception classes, including `TimeoutError` and `ConnectionError`.
10
+ - Ships RBI files so Sorbet users get types for the gem.
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2022-2026 Sophie Déziel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,336 @@
1
+ # OctoPrint Ruby Gem
2
+
3
+ A comprehensive, type-safe Ruby wrapper for OctoPrint's REST API with full Sorbet integration.
4
+
5
+ ## ✨ Key Features
6
+
7
+ - **🛡️ Type Safety**: Full Sorbet type annotations with compile-time error checking
8
+ - **🔥 Smart Error Handling**: HTTP status codes mapped to specific exception types
9
+ - **📦 Comprehensive API Coverage**: Files, jobs, printer state and commands, printer profiles, connection, access control, settings, timelapse, logs, system commands and more
10
+ - **🧪 Exceptional Quality**: 100% line coverage, enforced in CI
11
+ - **🎯 Multi-Printer Support**: Manage multiple OctoPrint instances with thread-safe clients
12
+ - **⚡ Modern Ruby**: Built for Ruby 3.3+ with Zeitwerk autoloading and ActiveSupport integration
13
+
14
+ ## Installation
15
+
16
+ ### Gemfile installation
17
+
18
+ Add this line to your application's Gemfile:
19
+
20
+ ```Ruby
21
+ gem 'octoprint'
22
+ ```
23
+
24
+ or run in the terminal
25
+
26
+ bundle add octoprint
27
+
28
+
29
+ And then execute:
30
+
31
+ bundle install
32
+
33
+ ### global manual installation
34
+
35
+ gem install octoprint
36
+
37
+ ## Usage
38
+
39
+ ```ruby
40
+ require 'octoprint'
41
+
42
+ # Configure globally for single printer
43
+ Octoprint.configure(host: 'https://octopi.local/', api_key: 'your_api_key')
44
+
45
+ # List files with full type safety
46
+ result = Octoprint::Files.list # => Octoprint::Files
47
+ result.files.first.name # => String (typed)
48
+ result.files.first.type_path # => Array<String> (typed)
49
+
50
+ # Get current job with progress tracking
51
+ job = Octoprint::Job.get # => Octoprint::Job
52
+ puts "#{job.information.file[:name]}: #{job.progress.completion}%" if job.progress.completion
53
+
54
+ # Upload and start a print job (location defaults to Octoprint::Location::Local)
55
+ Octoprint::Files.upload("awesome_model.gcode")
56
+ Octoprint::Files.select(filename: "awesome_model.gcode")
57
+ Octoprint::Job.start
58
+ ```
59
+
60
+ Or select and start printing in one call: `Octoprint::Files.select(filename: "awesome_model.gcode", print: true)`.
61
+
62
+ To generate an app key on your Octoprint's instance, log in to it, click on the Settings button in the top menu and then go to the "Application Keys".
63
+
64
+ The gem always authenticates with this API key and doesn't keep cookies. To authenticate on the push API (WebSocket), get a session key with a passive login: `Octoprint::Access::Users.login.session`.
65
+
66
+ ## 🛡️ Type Safety with Sorbet
67
+
68
+ This gem provides complete type safety with Sorbet integration:
69
+
70
+ ```ruby
71
+ # All models are fully typed
72
+ job = Octoprint::Job.get
73
+ job.information.file # => Hash | nil (typed), e.g. job.information.file[:name]
74
+ job.progress.completion # => Float | nil (typed)
75
+ ```
76
+
77
+ **Benefits:**
78
+ - **Compile-time Error Detection**: Catch errors before runtime with `srb tc`
79
+ - **IDE Integration**: Full autocomplete and type information (requires proper IDE setup, for example: ruby-lsp and sorbet plugins for VSCode)
80
+ - **Refactoring Safety**: Type-checked code changes across the entire codebase
81
+ - **No Runtime Overhead**: Signatures are inline RBS comments (`#: (String) -> Files`), so nothing is type-checked at runtime
82
+ - **Ships its own RBIs**: the `rbi/` folder is included in the gem, so Tapioca picks up the types in apps that use Sorbet
83
+
84
+ ## 🔥 Smart Error Handling
85
+
86
+ HTTP errors are automatically mapped to specific exception types for clean error flow:
87
+
88
+ ```ruby
89
+ begin
90
+ Octoprint::Files.select(filename: "missing.gcode")
91
+ rescue Octoprint::Exceptions::NotFoundError => e
92
+ # Handle 404 errors specifically
93
+ puts "Resource not found: #{e.message}"
94
+ rescue Octoprint::Exceptions::BadRequestError => e
95
+ # Handle 400 errors specifically
96
+ puts "Invalid request: #{e.message}"
97
+ rescue Octoprint::Exceptions::AuthenticationError => e
98
+ # Handle 403 errors specifically
99
+ puts "Authentication failed: #{e.message}"
100
+ rescue Octoprint::Exceptions::Error => e
101
+ # Catch-all for every error raised by the gem
102
+ puts "OctoPrint error: #{e.message}"
103
+ end
104
+ ```
105
+
106
+ **Exception Types** (all under `Octoprint::Exceptions`):
107
+ - `Error` - Base class of every exception below, handy as a catch-all rescue
108
+ - `AuthenticationError` (403) - Invalid API key or permissions
109
+ - `BadRequestError` (400) - Invalid parameters or request format
110
+ - `NotFoundError` (404) - Resource doesn't exist
111
+ - `ConflictError` (409) - Resource conflicts or state issues
112
+ - `UnsupportedMediaTypeError` (415) - Invalid file format
113
+ - `InternalServerError` (500) - Server-side errors
114
+ - `UnknownError` - Fallback for unexpected responses
115
+ - `ConnectionError` - The server can't be reached (connection refused, unreachable host, ...)
116
+ - `TimeoutError` - The server didn't respond within the configured timeouts (a subclass of `ConnectionError`)
117
+ - `MissingCredentialsError` - `Octoprint::Client.new` was given a `nil` host or API key
118
+
119
+ ## 📦 Comprehensive API Coverage
120
+
121
+ This gem aims to provide complete coverage of OctoPrint's REST API:
122
+
123
+ | **Category** | **Features** |
124
+ |---|---|
125
+ | **Files** | List, get, upload, delete, create folders, select/unselect, slice STL files, copy/move, download URLs |
126
+ | **Jobs** | Current job info, progress tracking, start/cancel/restart/pause/resume |
127
+ | **Printer** | Printer state, temperatures with history, print head jog/home, tool/bed/chamber temperatures, extrusion, SD card, arbitrary commands, custom controls, last error |
128
+ | **Printer Profiles** | List, get, create, update, and delete printer profiles |
129
+ | **Slicing** | List slicers and their slicing profiles; get, add, update, and delete slicing profiles |
130
+ | **Connection** | Connect/disconnect printer, connection settings and options |
131
+ | **Languages** | List, upload, and delete language packs |
132
+ | **Logs** | List and delete log files, download URLs |
133
+ | **Timelapse** | List and delete timelapses, render or delete unrendered ones, change the timelapse config |
134
+ | **Access** | Users (list, add, get, update, delete, change password, user settings, API keys, current user, login (session key for the push API) and logout), groups (list, add, get, update, delete), permissions (list) |
135
+ | **Settings** | Get and save settings, regenerate the API key, fetch templates, typed webcam settings |
136
+ | **System Commands** | List commands (all or by source) and execute them |
137
+ | **Wizard** | Get wizard data and finish wizards |
138
+ | **Utilities** | Test paths, URLs, server connectivity, DNS resolution, and addresses |
139
+ | **Server** | Server version (`ServerVersion`) and server status / safe mode (`ServerInformation`) |
140
+
141
+ ```ruby
142
+ # File management
143
+ Octoprint::Files.upload("model.gcode", location: Octoprint::Location::Local)
144
+ Octoprint::Files.slice(filename: "model.stl", profile: { slicer: "cura" })
145
+
146
+ # Job control
147
+ job = Octoprint::Job.get
148
+ Octoprint::Job.start if job.state == "Operational"
149
+
150
+ # Printer control
151
+ printer = Octoprint::Printer.get(history: true, limit: 10)
152
+ printer.temperature.tool(0).actual # => 214.8
153
+ Octoprint::Printer::Printhead.home(axes: %w[x y])
154
+ Octoprint::Printer::Tool.target(tool0: 220)
155
+ Octoprint::Printer::Bed.target(60)
156
+ Octoprint::Printer::Command.send_commands(["M106 S255", "M117 Hello"])
157
+
158
+ # Timelapses
159
+ Octoprint::Timelapse.get(unrendered: true).unrendered.each { |job| Octoprint::Timelapse.render(name: job.name) }
160
+ Octoprint::Timelapse.update_config(type: "timed", interval: 10, save: true)
161
+
162
+ # Printer profiles
163
+ profile = Octoprint::PrinterProfiles.create(
164
+ profile: { id: "ender3", name: "Ender 3 Pro", model: "Ender 3 Pro" }
165
+ ) # => Octoprint::PrinterProfiles::PrinterProfile
166
+
167
+ # Slicing profiles
168
+ Octoprint::Slicing.list[:curalegacy].profiles.keys # => [:high_quality]
169
+ Octoprint::Slicing.add_profile(slicer: "curalegacy", key: "draft", display_name: "Draft", data: { layer_height: 0.3 })
170
+ Octoprint::Slicing.get_profile(slicer: "curalegacy", key: "draft").data # => { layer_height: 0.3 }
171
+
172
+ # Connection management
173
+ Octoprint::Connection.connect(port: "/dev/ttyUSB0", baudrate: 115200)
174
+ ```
175
+
176
+ ### Flexibility
177
+
178
+ This gem is built to offer multiple options to interact with Octoprint's apis. Depending on your use case, you can configure the gem for only one Octoprint server, or you can generate an API client to use for each server.
179
+
180
+ #### Example 1: Use in a Rails app, with a single Octoprint server
181
+
182
+ ```Ruby
183
+ # config/initializers/octoprint.rb
184
+ Octoprint.configure(host: 'https://octopi.local/', api_key: 'j98G2nsJq...')
185
+
186
+ # app/controllers/printers_controller.rb
187
+ class PrintersController < ApplicationController
188
+ def connect
189
+ Octoprint::Connection.connect
190
+ end
191
+ end
192
+ ```
193
+
194
+ #### Example 2: Manage multiple printers in a ruby script
195
+
196
+ ```Ruby
197
+ ender3 = Octoprint::Client.new(host: 'http://192.168.0.145', api_key: 'asdf')
198
+ cr10 = Octoprint::Client.new(host: 'http://192.168.0.167', api_key: 'ghjk')
199
+
200
+ files = []
201
+
202
+ ender3.use do
203
+ files << Octoprint::Files.list
204
+ end
205
+
206
+ cr10.use do
207
+ files << Octoprint::Files.list
208
+ end
209
+ ```
210
+
211
+ #### Timeouts
212
+
213
+ By default, the client waits up to 2 seconds for the connection to open and up to 3 seconds for each read or write, so an offline printer can't hang your app. Pass `open_timeout:` and `timeout:` (in seconds) to `Octoprint.configure` or `Octoprint::Client.new` to change them. Raise `timeout:` for large file uploads. A `nil` `timeout:` falls back to the HTTP adapter's default (60 seconds for Net::HTTP), and a `nil` `open_timeout:` falls back to `timeout:`.
214
+
215
+ ```Ruby
216
+ client = Octoprint::Client.new(host: 'http://192.168.0.145', api_key: 'asdf', open_timeout: 1, timeout: 30)
217
+
218
+ begin
219
+ client.use { Octoprint::Job.get }
220
+ rescue Octoprint::Exceptions::ConnectionError # also rescues Octoprint::Exceptions::TimeoutError
221
+ puts "Printer is offline"
222
+ end
223
+ ```
224
+
225
+ #### Webcam settings
226
+
227
+ `Octoprint::Settings.webcam` returns the webcam settings as a typed object. It supports the multi-webcam settings of OctoPrint 1.9+ (using the default webcam) and the legacy settings of older versions.
228
+
229
+ ```Ruby
230
+ webcam = Octoprint::Settings.webcam # => Octoprint::Settings::Webcam
231
+ webcam.enabled # => true
232
+ webcam.stream_url # => "/webcam/?action=stream" (can be relative to the host)
233
+ webcam.snapshot_url # => "http://localhost:8080/?action=snapshot"
234
+
235
+ # Already have the settings? Skip the extra request
236
+ Octoprint::Settings::Webcam.from_settings(Octoprint::Settings.get)
237
+ ```
238
+
239
+ ## 🧪 Testing & Code Quality
240
+
241
+ This gem maintains quality standards:
242
+
243
+ ### Test Coverage
244
+ - **100% Line Coverage**
245
+ - **API calls recorded with VCR**: Real API interactions recorded and replayed, ensuring tests ran in real conditions while keeping CI simple and fast.
246
+
247
+ ### Code Quality
248
+ - **RuboCop**
249
+ - **Sorbet Type Checking**
250
+
251
+ ```bash
252
+ # Run all quality checks
253
+ bundle exec rspec
254
+ bundle exec rubocop
255
+ bundle exec srb tc
256
+ ```
257
+
258
+ ## Development
259
+
260
+ After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
261
+
262
+ To install this gem onto your local machine, run `bundle exec rake install`. Releases are published from CI, see [Releasing](#releasing).
263
+
264
+ ### Testing with Octoprint
265
+
266
+ You can test with an existing octoprint instance that you have, or you can setup a test [octoprint](https://octoprint.org/download/) instance using the [virtual printer plugin](https://docs.octoprint.org/en/main/bundledplugins/virtual_printer.html).
267
+
268
+ There are many ways you can set that up; using Docker, pip on your local machine or use a raspberry pi, and many more options. Pick the one that works for you.
269
+
270
+ As a convenience, here is the test setup I use, using Docker:
271
+
272
+ ```bash
273
+ brew install --cask docker # Install docker on a mac, if not already installed.
274
+
275
+ # Once Docker is started
276
+ docker run -d -p 5050:80 --name octoprint octoprint/octoprint
277
+ ```
278
+
279
+ Then, open http://localhost:5050/ and go through the setup wizard.
280
+
281
+ Enable the virtual printer plugin.
282
+
283
+ Go to Settings > Application keys and generate a new API key.
284
+
285
+ Set the `OCTOPRINT_HOST` and `OCTOPRINT_API_KEY` environment variables in your preferred way. For convenience, there is an example `.env` that you can copy. Some development tools will recognize that file and automatically load its content as environment variables. Copy it by entering `cp .env.example .env` in your terminal and add your Octoprint's configuration to the newly created `.env` file. This file is ignored by git, so it is safe to edit. VCR is configured to filter that data out of cassettes.
286
+
287
+ Remember, you should never commit your credentials to git. With the current configuration, you should never have to.
288
+
289
+ ### Recorded HTTP requests for the test suite
290
+
291
+ This project uses VCR to record the HTTP interactions with an Octoprint's API. When you add tests, you can use existing cassettes or record new ones. You should never edit the cassettes manually. You can delete the files and re-record them as you need.
292
+
293
+ If you need all request to pass through while developing, you can add the `:wip` flag to your tests. It will prevent cassettes from recording until you remove the flag. Remember to remove it and record all missing cassettes before you commit your changes. More information here: https://link.medium.com/QU7ZgM8P9nb
294
+
295
+ example:
296
+ ```Ruby
297
+ it "calls the API", :wip, vcr: {cassette_name: '/currentuser'} do
298
+ result = Octoprint::Access::User.current
299
+
300
+ expect(result).to be_a Octoprint::Access::User
301
+ expect(result.name).to eq 'sophie'
302
+ end
303
+ ```
304
+
305
+ It is preferable to have the test setup and teardown making all the required operations so deleting all cassettes to re-record them results in a successful full run, in any order of the tests.
306
+
307
+ For example: if a file is required on the octoprint instance in order to make an API call referencing that file, the test setup should upload it.
308
+
309
+ However, it is not realistic to apply this strictly, some exceptions exist. It is not recommended to delete all cassettes to record them again. Only re-record new cassettes if strictly needed.
310
+
311
+ ### Releasing
312
+
313
+ Publishing a GitHub Release for a `vX.Y.Z` tag runs `.github/workflows/release.yml`. It runs the lint and test workflows, checks that the tag matches `Octoprint::VERSION`, publishes the gem to [rubygems.org](https://rubygems.org) through [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (no API key), replaces the release notes with the version's CHANGELOG section and attaches the `.gem`.
314
+
315
+ 1. Bump `VERSION` in `lib/octoprint/version.rb`.
316
+ 2. In `CHANGELOG.md`, move the entries under `## [X.Y.Z] - YYYY-MM-DD`. The heading must contain `[X.Y.Z]` or the release stops before publishing.
317
+ 3. Open a PR and merge it into `main`.
318
+ 4. On GitHub, draft a new release: create the tag `vX.Y.Z` on `main`, and publish it. Saving a draft doesn't trigger anything.
319
+
320
+ The release is public before CI finishes. If lint, tests or the version and CHANGELOG checks fail, nothing is published: fix the problem on `main`, delete the release and its tag, and publish it again.
321
+
322
+ Don't run `bundle exec rake release` locally.
323
+
324
+ One-time setup, before the first release: on rubygems.org, add a pending trusted publisher (Profile → Trusted publishers) for gem `octoprint`, repository `sophiedeziel/octoprint`, workflow `release.yml` and environment `rubygems`. It becomes a regular trusted publisher after the first push.
325
+
326
+ ## Contributing
327
+
328
+ Bug reports and pull requests are welcome on GitHub at https://github.com/sophiedeziel/octoprint. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sophiedeziel/octoprint/blob/main/CODE_OF_CONDUCT.md).
329
+
330
+ ## License
331
+
332
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
333
+
334
+ ## Code of Conduct
335
+
336
+ Everyone interacting in the Octoprint project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sophiedeziel/octoprint/blob/main/CODE_OF_CONDUCT.md).
@@ -0,0 +1,88 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ module Access
6
+ # Represents a group in the OctoPrint access control system
7
+ #
8
+ # @example
9
+ # group = Octoprint::Access::Group.new(
10
+ # key: "operators",
11
+ # name: "Operators",
12
+ # description: "Can operate the printer",
13
+ # permissions: ["CONTROL", "MONITOR"],
14
+ # subgroups: [],
15
+ # needs_role: [],
16
+ # default: false,
17
+ # removable: true,
18
+ # changeable: true,
19
+ # toggleable: false
20
+ # )
21
+ class Group
22
+ include AutoInitializable
23
+ include Deserializable
24
+
25
+ # @!attribute [r] key
26
+ # @return [String] The group key/identifier
27
+ auto_attr :key, type: String
28
+
29
+ # @!attribute [r] name
30
+ # @return [String] The human-readable name
31
+ auto_attr :name, type: String
32
+
33
+ # @!attribute [r] description
34
+ # @return [String] Description of the group
35
+ auto_attr :description, type: String
36
+
37
+ # @!attribute [r] permissions
38
+ # @return [Array<String>] Permissions assigned to this group
39
+ auto_attr :permissions, type: String, array: true
40
+
41
+ # @!attribute [r] subgroups
42
+ # @return [Array<String>] Subgroups included in this group
43
+ auto_attr :subgroups, type: String, array: true
44
+
45
+ # @!attribute [r] needs_role
46
+ # @return [Array<String>] Roles needed for this group
47
+ auto_attr :needs_role, type: String, array: true
48
+
49
+ # @!attribute [r] needs
50
+ # @return [Hash] Needs information with groups and roles
51
+ auto_attr :needs, type: Hash
52
+
53
+ # @!attribute [r] dangerous
54
+ # @return [Boolean] Whether this group is dangerous
55
+ auto_attr :dangerous, type: Types::Boolean
56
+
57
+ # @!attribute [r] default
58
+ # @return [Boolean] Whether this is a default group
59
+ auto_attr :default, type: Types::Boolean
60
+
61
+ # @!attribute [r] removable
62
+ # @return [Boolean] Whether this group can be removed
63
+ auto_attr :removable, type: Types::Boolean
64
+
65
+ # @!attribute [r] changeable
66
+ # @return [Boolean] Whether this group can be changed
67
+ auto_attr :changeable, type: Types::Boolean
68
+
69
+ # @!attribute [r] toggleable
70
+ # @return [Boolean] Whether this group can be toggled
71
+ auto_attr :toggleable, type: Types::Boolean
72
+
73
+ # @!attribute [r] extra
74
+ # @return [Hash] Additional attributes from the API
75
+ auto_attr :extra, type: Hash
76
+
77
+ auto_initialize!
78
+
79
+ deserialize_config do
80
+ rename needsRole: :needs_role
81
+ transform do |data|
82
+ # Handle the needs structure which comes as a hash instead of array
83
+ data[:needs_role] = data[:needs][:role] if data[:needs].is_a?(Hash) && data[:needs][:role]
84
+ end
85
+ end
86
+ end
87
+ end
88
+ end
@@ -0,0 +1,166 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ module Access
6
+ # Provides access to the OctoPrint groups API
7
+ #
8
+ # @see https://docs.octoprint.org/en/master/api/access.html#groups
9
+ class Groups < BaseResource
10
+ resource_path("/api/access/groups")
11
+
12
+ # Retrieve a list of groups
13
+ #
14
+ # Requires the SETTINGS permission.
15
+ #
16
+ # @example Get all groups
17
+ # groups = Octoprint::Access::Groups.list
18
+ # groups.each do |group|
19
+ # puts "#{group.key}: #{group.name}"
20
+ # end
21
+ #
22
+ # @return [Array<Group>] An array of Group objects
23
+ #: -> Array[Group]
24
+ def self.list
25
+ response = fetch_resource(deserialize: false)
26
+ groups_data = response[:groups] || response["groups"] || []
27
+ groups_data.map { |group_data| Group.deserialize(group_data) }
28
+ end
29
+
30
+ # Add a new group
31
+ #
32
+ # Requires the SETTINGS permission and a recent credentials check.
33
+ #
34
+ # @example Create a new group
35
+ # group = Octoprint::Access::Groups.add(
36
+ # key: "operators",
37
+ # name: "Operators",
38
+ # description: "Can operate the printer",
39
+ # permissions: ["CONTROL", "MONITOR"],
40
+ # subgroups: [],
41
+ # default: false
42
+ # )
43
+ #
44
+ # @param key [String] The group's identifier
45
+ # @param name [String] The group's human-readable name
46
+ # @param description [String] Description of the group
47
+ # @param permissions [Array<String>] Permissions to assign
48
+ # @param subgroups [Array<String>] Subgroups to include
49
+ # @param default [Boolean] Whether this is a default group
50
+ # @return [Array<Group>] The created groups
51
+ #: (
52
+ #| key: String,
53
+ #| name: String,
54
+ #| description: String,
55
+ #| permissions: Array[String],
56
+ #| subgroups: Array[String],
57
+ #| default: bool
58
+ #| ) -> Array[Group]
59
+ def self.add(key:, name:, description:, permissions:, subgroups:, default:)
60
+ response = client.request(
61
+ @path,
62
+ http_method: :post,
63
+ body: {
64
+ key: key,
65
+ name: name,
66
+ description: description,
67
+ permissions: permissions,
68
+ subgroups: subgroups,
69
+ default: default
70
+ },
71
+ headers: {},
72
+ options: {}
73
+ )
74
+ groups_data = response[:groups] || response["groups"] || []
75
+ groups_data.map { |group_data| Group.deserialize(group_data) }
76
+ end
77
+
78
+ # Retrieve a specific group
79
+ #
80
+ # Requires the SETTINGS permission.
81
+ #
82
+ # @example Get a specific group
83
+ # group = Octoprint::Access::Groups.get(key: "operators")
84
+ #
85
+ # @param key [String] The group's identifier
86
+ # @return [Group] The requested group
87
+ #: (key: String) -> Group
88
+ def self.get(key:)
89
+ response = fetch_resource(key, deserialize: false)
90
+ Group.deserialize(response)
91
+ end
92
+
93
+ # Update an existing group
94
+ #
95
+ # Requires the SETTINGS permission and a recent credentials check.
96
+ #
97
+ # @example Update a group
98
+ # group = Octoprint::Access::Groups.update(
99
+ # key: "operators",
100
+ # params: {
101
+ # description: "Updated description",
102
+ # permissions: ["CONTROL", "MONITOR", "FILES_LIST"]
103
+ # }
104
+ # )
105
+ #
106
+ # @param key [String] The group's identifier
107
+ # @param params [Hash] The attributes to update
108
+ # @return [Array<Group>] The created groups
109
+ #: (key: String, params: Hash[Symbol, untyped]) -> Array[Group]
110
+ def self.update(key:, params:)
111
+ path = [@path, key].join("/")
112
+ response = client.request(
113
+ path,
114
+ http_method: :put,
115
+ body: params,
116
+ headers: {},
117
+ options: {}
118
+ )
119
+
120
+ groups_data = response[:groups] || response["groups"] || []
121
+ groups_data.map { |group_data| Group.deserialize(group_data) }
122
+ end
123
+
124
+ # Delete a group
125
+ #
126
+ # Requires the SETTINGS permission and a recent credentials check.
127
+ #
128
+ # @example Delete a group
129
+ # Octoprint::Access::Groups.delete(key: "operators")
130
+ #
131
+ # @param key [String] The group's identifier
132
+ # @return [void]
133
+ #: (
134
+ #| ?key: String?,
135
+ #| ?path: String,
136
+ #| ?params: Hash[Symbol, untyped],
137
+ #| ?headers: Hash[Symbol, untyped],
138
+ #| ?options: Hash[Symbol, untyped]
139
+ #| ) -> untyped
140
+ def self.delete(key: nil, path: @path, params: {}, headers: {}, options: {})
141
+ if key
142
+ # Group deletion case - ignore path parameter and construct our own
143
+ group_path = [@path, key].join("/")
144
+ delete_resource(group_path)
145
+ nil
146
+ else
147
+ # Fall back to base behavior
148
+ super(path: path, params: params, headers: headers, options: options)
149
+ end
150
+ end
151
+
152
+ # Delete a resource at the given path
153
+ #: (String path) -> void
154
+ def self.delete_resource(path)
155
+ client.request(
156
+ path,
157
+ http_method: :delete,
158
+ body: nil,
159
+ headers: {},
160
+ options: {}
161
+ )
162
+ nil
163
+ end
164
+ end
165
+ end
166
+ end