diff --git a/CHANGELOG.md b/CHANGELOG.md index 5654fd2..a5563c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -# HotCell changelog +# Hot Cell changelog This changelog covers these gems, which release together on the same version: @@ -58,9 +58,9 @@ gem but are what an operator runs against their own image. Some actions that application developers should consider taking when upgrading from an earlier version: -* Replace the application's Yabeda integration for HotCell with the `yabeda-hotcell` gem. The README's "Metrics collection" lists the gem's metrics for comparison with the application's dashboards and alerts. -* Remove the log line that the application writes for each HotCell call, in a `perform.hot_cell` subscriber or in its Yabeda integration. `HotCell::LogSubscriber` writes this line now; see the README's "Application logs". -* Replace the application's HotCell health endpoints with `HotCell::HealthController` and `HotCell::DiagnosticsController`. The README's "Rails healthcheck" shows the routes and the authentication for the diagnostics route. +* Replace the application's Yabeda integration for Hot Cell with the `yabeda-hotcell` gem. The README's "Metrics collection" lists the gem's metrics for comparison with the application's dashboards and alerts. +* Remove the log line that the application writes for each Hot Cell call, in a `perform.hot_cell` subscriber or in its Yabeda integration. `HotCell::LogSubscriber` writes this line now; see the README's "Application logs". +* Replace the application's Hot Cell health endpoints with `HotCell::HealthController` and `HotCell::DiagnosticsController`. The README's "Rails healthcheck" shows the routes and the authentication for the diagnostics route. * Replace the cell's copies of `examples/operations/echo.rb` and `reopen.rb` with `require "hot_cell/health_operations"`, and change the application's clients to call `health.echo` and `health.reopen`. See the README's "Rails healthcheck". ### HotCell::Server diff --git a/README.md b/README.md index ed63bb2..1baf7b0 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,6 @@ worker process under strict limits, and returns the result or writes it to the o ## Status -This is pre-release software. It may break in interesting ways. Use it with caution until the v1.0 -release. - The Active Storage gems need Rails 8.2, which is unreleased. Track `rails/rails` `main` until it ships. See [Active Storage operations](docs/active-storage.md). @@ -130,7 +127,7 @@ HotCell.register "active_storage", permanent: MyApp::UnprocessableUpload, transient: MyApp::ConversionTemporarilyUnavailable -# Warns at boot about a cell that is unreachable, slower than this client waits, in the wrong group, or on another hotcell version. +# Warns at boot about a cell that is unreachable, slower than this client waits, in the wrong group, or on another Hot Cell version. Rails.application.config.after_initialize { HotCell.describe_cells } ``` diff --git a/Rakefile b/Rakefile index 8e3328b..fb80e8a 100644 --- a/Rakefile +++ b/Rakefile @@ -1,6 +1,6 @@ # frozen_string_literal: true -# The hotcell gems and yabeda-hotcell need no tools and no container: their suites run on fixture operations in +# The `hotcell-*` gems and yabeda-hotcell need no tools and no container: their suites run on fixture operations in # a few seconds, and so does the development cell the battery drives. The two activestorage-hotcell gems convert # real files and need libvips, mutool, ffmpeg and ffprobe installed. That split is a design property rather # than an accident, so the tasks keep it visible: `test:hotcell` is what CI runs on a machine with nothing diff --git a/activestorage-hotcell-client/README.md b/activestorage-hotcell-client/README.md index 933dc08..a3d1255 100644 --- a/activestorage-hotcell-client/README.md +++ b/activestorage-hotcell-client/README.md @@ -1,3 +1,3 @@ # activestorage-hotcell-client -Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README. +Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README. diff --git a/activestorage-hotcell-client/activestorage-hotcell-client.gemspec b/activestorage-hotcell-client/activestorage-hotcell-client.gemspec index 56d4f53..ab360a6 100644 --- a/activestorage-hotcell-client/activestorage-hotcell-client.gemspec +++ b/activestorage-hotcell-client/activestorage-hotcell-client.gemspec @@ -9,10 +9,10 @@ Gem::Specification.new do |spec| spec.email = [ "mike@37signals.com" ] spec.license = "MIT" spec.homepage = "https://github.com/basecamp/hotcell" - spec.summary = "Point Active Storage's transformer, analyzer, and previewers at a HotCell." + spec.summary = "Point Active Storage's transformer, analyzer, and previewers at a Hot Cell." spec.description = <<~TEXT Drop-in replacements for Active Storage's variant processor, analyzers, and previewers. Configure - Rails with these classes and variants, image and media analysis, and previews run in a HotCell + Rails with these classes and variants, image and media analysis, and previews run in a Hot Cell container instead of in the application process. TEXT diff --git a/activestorage-hotcell-client/lib/active_storage/hot_cell/client/analyzers/video.rb b/activestorage-hotcell-client/lib/active_storage/hot_cell/client/analyzers/video.rb index d014d83..fc5eb02 100644 --- a/activestorage-hotcell-client/lib/active_storage/hot_cell/client/analyzers/video.rb +++ b/activestorage-hotcell-client/lib/active_storage/hot_cell/client/analyzers/video.rb @@ -10,7 +10,7 @@ module HotCell module Client module Analyzers # Rails' VideoAnalyzer shells out to ffprobe inside the application process. Moving ffprobe into a - # cell means this has to move with it, or an application that adopts hotcell still analyzes media in + # cell means this has to move with it, or an application that adopts Hot Cell still analyzes media in # its own process and cannot take ffprobe out of its image — the incomplete move for exactly the # media type a cell exists to isolate. # diff --git a/activestorage-hotcell-server/README.md b/activestorage-hotcell-server/README.md index b96f580..f61373d 100644 --- a/activestorage-hotcell-server/README.md +++ b/activestorage-hotcell-server/README.md @@ -1,3 +1,3 @@ # activestorage-hotcell-server -Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README. +Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README. diff --git a/activestorage-hotcell-server/activestorage-hotcell-server.gemspec b/activestorage-hotcell-server/activestorage-hotcell-server.gemspec index b103970..0629b10 100644 --- a/activestorage-hotcell-server/activestorage-hotcell-server.gemspec +++ b/activestorage-hotcell-server/activestorage-hotcell-server.gemspec @@ -11,7 +11,7 @@ Gem::Specification.new do |spec| spec.homepage = "https://github.com/basecamp/hotcell" spec.summary = "The operations a cell runs on behalf of Active Storage." spec.description = <<~TEXT - The HotCell operations behind activestorage-hotcell-client: image transformation with libvips or + The Hot Cell operations behind activestorage-hotcell-client: image transformation with libvips or ImageMagick, image and media analysis, PDF previews with mutool or poppler, and video previews with ffmpeg. Install it in the cell, with the tools the operations you load require. TEXT diff --git a/bin/conformance b/bin/conformance index b0a4c5f..b66d639 100755 --- a/bin/conformance +++ b/bin/conformance @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Does this image actually support hotcell? Boots IMAGE as a cell with the accessory's real flags — +# Does this image actually support Hot Cell? Boots IMAGE as a cell with the accessory's real flags — # network: none, cap-drop ALL, a read-only root, a noexec tmpfs — with the example operations mounted and # HOTCELL_DIR pointed somewhere non-default, then drives the shared battery from a second container over # a named volume. The socket appearing where HOTCELL_DIR said proves the env contract; the descriptor diff --git a/docs/active-storage.md b/docs/active-storage.md index 731f3ce..f0a673a 100644 --- a/docs/active-storage.md +++ b/docs/active-storage.md @@ -47,7 +47,7 @@ Rails' own classes mix freely with these in the `analyzers` and `previewers` arr some work into a cell: ```ruby -# PDF previews handled by HotCell, video previews still in the application +# PDF previews handled by Hot Cell, video previews still in the application config.active_storage.previewers = [ ActiveStorage::HotCell::Client::Previewers::Pdf::Mutool, ActiveStorage::Previewer::VideoPreviewer ] ``` diff --git a/docs/client-api.md b/docs/client-api.md index eb10f52..a790018 100644 --- a/docs/client-api.md +++ b/docs/client-api.md @@ -15,7 +15,7 @@ sources: # Client API -This page describes the application side of HotCell: registering cells with `HotCell.register`, writing +This page describes the application side of Hot Cell: registering cells with `HotCell.register`, writing `HotCell::Client` subclasses, the boot checks, and the group that the application shares with each cell. For the cell side of the call, see [Operation API](operation-api.md). diff --git a/docs/contributing/guide.md b/docs/contributing/guide.md index 750ccda..39fb4f7 100644 --- a/docs/contributing/guide.md +++ b/docs/contributing/guide.md @@ -20,8 +20,8 @@ your own application — start with [README.md](../../README.md) instead. bundle install ``` -That is enough for the hotcell gems and for the example cell. It is deliberately enough: **the -hotcell gems need no container and no tool installed**, and `rake test:hotcell` is what keeps that honest — +That is enough for the `hotcell-*` gems and for the example cell. It is deliberately enough: **the +`hotcell-*` gems need no container and no tool installed**, and `rake test:hotcell` is what keeps that honest — CI runs it on a machine with nothing on it. Fixture operations stand in for the work, so the protocol, the fork, the descriptor passing, the limits and the reap are all exercised in milliseconds. @@ -55,7 +55,7 @@ The container checks are scripts rather than rake tasks, because they need Docke ``` bin/example-image # install the cell scaffold and build what it wrote -bin/conformance IMAGE # does this image support hotcell? +bin/conformance IMAGE # does this image support Hot Cell? bin/load IMAGE [SCENARIO] [SECONDS] [THREADS] ``` @@ -124,7 +124,7 @@ of `rake test:hotcell`, so it runs with the rest of the suite, on Linux and macO It is Docker-free on purpose. See "Cells run uncontainerized in development" below. -### `bin/conformance IMAGE` — does this image support hotcell? +### `bin/conformance IMAGE` — does this image support Hot Cell? The real use case is somebody building their own cell image and wanting to know whether it works. It boots `IMAGE` with the accessory's real flags — `network: none`, `cap-drop ALL`, a read-only root, a `noexec` diff --git a/hotcell-client-legacy/README.md b/hotcell-client-legacy/README.md index 4438862..fa20db7 100644 --- a/hotcell-client-legacy/README.md +++ b/hotcell-client-legacy/README.md @@ -1,3 +1,3 @@ # hotcell-client-legacy -Part of [HotCell](https://github.com/basecamp/hotcell). See [docs/client-legacy.md](https://github.com/basecamp/hotcell/blob/master/docs/client-legacy.md). +Part of [Hot Cell](https://github.com/basecamp/hotcell). See [docs/client-legacy.md](https://github.com/basecamp/hotcell/blob/master/docs/client-legacy.md). diff --git a/hotcell-client-legacy/hotcell-client-legacy.gemspec b/hotcell-client-legacy/hotcell-client-legacy.gemspec index d4ed48d..05a5816 100644 --- a/hotcell-client-legacy/hotcell-client-legacy.gemspec +++ b/hotcell-client-legacy/hotcell-client-legacy.gemspec @@ -11,8 +11,8 @@ Gem::Specification.new do |spec| spec.email = [ "mike@37signals.com" ] spec.license = "MIT" spec.homepage = "https://github.com/basecamp/hotcell" - spec.summary = "Call a HotCell from a legacy Ruby version, with no dependencies." - spec.description = "Call an operation in a HotCell container from an application that cannot run " \ + spec.summary = "Call a Hot Cell from a legacy Ruby version, with no dependencies." + spec.description = "Call an operation in a Hot Cell container from an application that cannot run " \ "hotcell-client. One file, the standard library only, and legacy Ruby versions." spec.required_ruby_version = ">= 1.9.3" diff --git a/hotcell-client/README.md b/hotcell-client/README.md index d1130ba..91819b6 100644 --- a/hotcell-client/README.md +++ b/hotcell-client/README.md @@ -1,3 +1,3 @@ # hotcell-client -Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README. +Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README. diff --git a/hotcell-client/hotcell-client.gemspec b/hotcell-client/hotcell-client.gemspec index e364be2..3581d7e 100644 --- a/hotcell-client/hotcell-client.gemspec +++ b/hotcell-client/hotcell-client.gemspec @@ -9,9 +9,9 @@ Gem::Specification.new do |spec| spec.email = [ "mike@37signals.com" ] spec.license = "MIT" spec.homepage = "https://github.com/basecamp/hotcell" - spec.summary = "Call a HotCell from an application." + spec.summary = "Call a Hot Cell from an application." spec.description = <<~TEXT - Call operations that run in a HotCell container. Register a cell, subclass HotCell::Client to name + Call operations that run in a Hot Cell container. Register a cell, subclass HotCell::Client to name an operation, and call it with open file descriptors and a payload. Failures arrive classified as permanent or transient, as exception classes your application supplies. TEXT diff --git a/hotcell-client/lib/hot_cell/install/Dockerfile.tt b/hotcell-client/lib/hot_cell/install/Dockerfile.tt index 74708d3..77b187d 100644 --- a/hotcell-client/lib/hot_cell/install/Dockerfile.tt +++ b/hotcell-client/lib/hot_cell/install/Dockerfile.tt @@ -1,4 +1,4 @@ -# The cell's image. HotCell installed this file once; it is yours to customize, and nothing inherits +# The cell's image. Hot Cell installed this file once; it is yours to customize, and nothing inherits # from a published base image — this is the whole recipe. # # A cell carries a Ruby runtime and every gem in its loaded graph, all inside the blast radius, so treat diff --git a/hotcell-core/README.md b/hotcell-core/README.md index 36c4e8f..8253f17 100644 --- a/hotcell-core/README.md +++ b/hotcell-core/README.md @@ -1,3 +1,3 @@ # hotcell-core -Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README. +Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README. diff --git a/hotcell-core/hotcell-core.gemspec b/hotcell-core/hotcell-core.gemspec index 84cce3a..e4fd7b7 100644 --- a/hotcell-core/hotcell-core.gemspec +++ b/hotcell-core/hotcell-core.gemspec @@ -9,9 +9,9 @@ Gem::Specification.new do |spec| spec.email = [ "mike@37signals.com" ] spec.license = "MIT" spec.homepage = "https://github.com/basecamp/hotcell" - spec.summary = "The wire protocol shared by both sides of a HotCell." + spec.summary = "The wire protocol shared by both sides of a Hot Cell." spec.description = <<~TEXT - The wire protocol between an application and a HotCell container: the request and response format, + The wire protocol between an application and a Hot Cell container: the request and response format, file descriptor passing over SCM_RIGHTS, payload validation, and the error taxonomy. Both hotcell-client and hotcell-server depend on it. Install one of those rather than this. TEXT diff --git a/hotcell-server/README.md b/hotcell-server/README.md index af08741..db91bf5 100644 --- a/hotcell-server/README.md +++ b/hotcell-server/README.md @@ -1,3 +1,3 @@ # hotcell-server -Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README. +Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README. diff --git a/hotcell-server/hotcell-server.gemspec b/hotcell-server/hotcell-server.gemspec index 7560db3..d2592af 100644 --- a/hotcell-server/hotcell-server.gemspec +++ b/hotcell-server/hotcell-server.gemspec @@ -9,9 +9,9 @@ Gem::Specification.new do |spec| spec.email = [ "mike@37signals.com" ] spec.license = "MIT" spec.homepage = "https://github.com/basecamp/hotcell" - spec.summary = "Run a HotCell: the supervisor, the worker, and the operation API." + spec.summary = "Run a Hot Cell: the supervisor, the worker, and the operation API." spec.description = <<~TEXT - Runs a HotCell container. A supervisor listens on two Unix sockets, forks a worker for each request, + Runs a Hot Cell container. A supervisor listens on two Unix sockets, forks a worker for each request, and enforces a wall clock deadline and resource limits on it. Write the work as a subclass of HotCell::Operation. TEXT diff --git a/hotcell-server/lib/hot_cell/operation.rb b/hotcell-server/lib/hot_cell/operation.rb index 737bd70..f1c22b5 100644 --- a/hotcell-server/lib/hot_cell/operation.rb +++ b/hotcell-server/lib/hot_cell/operation.rb @@ -75,7 +75,7 @@ def limits(**values) # does not survive fork and the child waits on a pool with no threads. Not the first worker — every # worker. A later change that pre-warms the pool to save the fork cost is exactly what this forbids. # - # Note that a hotcell forks per request, continuously, so "before the fork" and "at boot" are not + # Note that a cell forks per request, continuously, so "before the fork" and "at boot" are not # the same moment the way they are in Puma. This runs once. def before_fork(&block) return collected(:@before_fork) if block.nil? diff --git a/yabeda-hotcell/README.md b/yabeda-hotcell/README.md index a1be775..54aa52a 100644 --- a/yabeda-hotcell/README.md +++ b/yabeda-hotcell/README.md @@ -1,3 +1,3 @@ # yabeda-hotcell -Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README. +Part of [Hot Cell](https://github.com/basecamp/hotcell). See the repository README. diff --git a/yabeda-hotcell/yabeda-hotcell.gemspec b/yabeda-hotcell/yabeda-hotcell.gemspec index 66b63f4..bfc882a 100644 --- a/yabeda-hotcell/yabeda-hotcell.gemspec +++ b/yabeda-hotcell/yabeda-hotcell.gemspec @@ -9,9 +9,9 @@ Gem::Specification.new do |spec| spec.email = [ "mike@37signals.com" ] spec.license = "MIT" spec.homepage = "https://github.com/basecamp/hotcell" - spec.summary = "Yabeda metrics for HotCell." + spec.summary = "Yabeda metrics for Hot Cell." spec.description = <<~TEXT - Yabeda metrics for an application that calls HotCell cells: a counter and a histogram for every call, + Yabeda metrics for an application that calls Hot Cell cells: a counter and a histogram for every call, and gauges polled from each local cell's control socket. TEXT