Skip to content

Commit be4c335

Browse files
samuel-williams-shopifysamuel-williams-shopify
committed
Update documentation.
1 parent b527468 commit be4c335

File tree

5 files changed

+47
-38
lines changed

5 files changed

+47
-38
lines changed

‎context/best-practices.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Place environments in `lib/my_library/environment/`:
6161
module MyLibrary
6262
module Environment
6363
module WebEnvironment
64-
include Async::Service::ContainerEnvironment
64+
include Async::Service::Managed::Environment
6565

6666
def service_class
6767
MyLibrary::Service::WebService
@@ -87,7 +87,7 @@ Place services in `lib/my_library/service/`:
8787
# lib/my_library/service/web_service.rb
8888
module MyLibrary
8989
module Service
90-
class WebService < Async::Service::ContainerService
90+
class WebService < Async::Service::Managed::Service
9191
private def format_title(evaluator, server)
9292
if server&.respond_to?(:connection_count)
9393
"#{self.name} [#{evaluator.host}:#{evaluator.port}] (#{server.connection_count} connections)"
@@ -98,7 +98,7 @@ module MyLibrary
9898

9999
def run(instance, evaluator)
100100
# Start your service and return the server object.
101-
# ContainerService handles container setup, health checking, and process titles.
101+
# Managed::Service handles container setup, health checking, and process titles.
102102
start_web_server(evaluator.host, evaluator.port)
103103
end
104104

@@ -112,13 +112,13 @@ module MyLibrary
112112
end
113113
```
114114

115-
### Use `ContainerEnvironment` for Services
115+
### Use `Managed::Environment` for Services
116116

117-
Include {ruby Async::Service::ContainerEnvironment} for services that run in containers using {ruby Async::Service::ContainerService}:
117+
Include {ruby Async::Service::Managed::Environment} for services that need robust lifecycle management using {ruby Async::Service::Managed::Service}:
118118

119119
```ruby
120120
module WebEnvironment
121-
include Async::Service::ContainerEnvironment
121+
include Async::Service::Managed::Environment
122122

123123
def service_class
124124
WebService
@@ -199,16 +199,16 @@ end
199199

200200
## Service Best Practices
201201

202-
### Use ContainerService as Base Class
202+
### Use `Managed::Service` as Base Class
203203

204-
Prefer `Async::Service::ContainerService` over `Generic` for most services:
204+
Prefer `Async::Service::Managed::Service` over `Generic` for most services:
205205

206206
```ruby
207-
class WebService < Async::Service::ContainerService
208-
# ContainerService automatically handles:
207+
class WebService < Async::Service::Managed::Service
208+
# Managed::Service automatically handles:
209209
# - Container setup with proper options.
210210
# - Health checking with process title updates.
211-
# - Integration with Formatting module.
211+
# - Preloading of scripts before startup.
212212

213213
private def format_title(evaluator, server)
214214
# Customize process title display
@@ -247,7 +247,7 @@ Try to keep process titles short and focused.
247247
Utilize the `start` and `stop` hooks to manage shared resources effectively:
248248

249249
```ruby
250-
class WebService < Async::Service::ContainerService
250+
class WebService < Async::Service::Managed::Service
251251
def start
252252
# Bind to the endpoint in the container:
253253
@endpoint = @evaluator.endpoint.bind
@@ -261,6 +261,8 @@ class WebService < Async::Service::ContainerService
261261
end
262262
```
263263

264+
These hooks are invoked **before** the container is setup (e.g. pre-forking).
265+
264266
## Testing Best Practices
265267

266268
### Test Environments in Isolation

‎context/service-architecture.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,8 @@ end
262262

263263
### Health Checking
264264

265+
For services using `Async::Service::Managed::Service`, health checking is handled automatically. For services extending `Generic`, you can set up health checking manually:
266+
265267
```ruby
266268
def setup(container)
267269
container_options = @evaluator.container_options
@@ -270,7 +272,7 @@ def setup(container)
270272
container.run(**container_options) do |instance|
271273
# Prepare your service.
272274

273-
Sync do
275+
Async do
274276
# Start your service.
275277

276278
# Set up health checking, if a timeout was specified:
@@ -282,6 +284,8 @@ def setup(container)
282284
end
283285
```
284286

287+
Note: `Async::Service::Managed::Service` automatically handles health checking, container options, and process title formatting, so you typically don't need to set this up manually.
288+
285289
## How They Work Together
286290

287291
The four layers interact in a specific pattern:
@@ -435,23 +439,21 @@ configuration = Async::Service::Configuration.load(["config/web.rb", "config/wor
435439
Create reusable configuration modules:
436440

437441
```ruby
438-
module ContainerEnvironment
442+
module ManagedEnvironment
443+
include Async::Service::Managed::Environment
444+
439445
def count
440446
4
441447
end
442448

443-
def restart
444-
true
445-
end
446-
447449
def health_check_timeout
448450
30
449451
end
450452
end
451453

452454
configuration = Async::Service::Configuration.build do
453455
service "my-service" do
454-
include ContainerEnvironment
456+
include ManagedEnvironment
455457
service_class MyService
456458
end
457459
end

‎guides/best-practices/readme.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Place environments in `lib/my_library/environment/`:
6161
module MyLibrary
6262
module Environment
6363
module WebEnvironment
64-
include Async::Service::ContainerEnvironment
64+
include Async::Service::Managed::Environment
6565

6666
def service_class
6767
MyLibrary::Service::WebService
@@ -87,7 +87,7 @@ Place services in `lib/my_library/service/`:
8787
# lib/my_library/service/web_service.rb
8888
module MyLibrary
8989
module Service
90-
class WebService < Async::Service::ContainerService
90+
class WebService < Async::Service::Managed::Service
9191
private def format_title(evaluator, server)
9292
if server&.respond_to?(:connection_count)
9393
"#{self.name} [#{evaluator.host}:#{evaluator.port}] (#{server.connection_count} connections)"
@@ -98,7 +98,7 @@ module MyLibrary
9898

9999
def run(instance, evaluator)
100100
# Start your service and return the server object.
101-
# ContainerService handles container setup, health checking, and process titles.
101+
# Managed::Service handles container setup, health checking, and process titles.
102102
start_web_server(evaluator.host, evaluator.port)
103103
end
104104

@@ -112,13 +112,13 @@ module MyLibrary
112112
end
113113
```
114114

115-
### Use `ContainerEnvironment` for Services
115+
### Use `Managed::Environment` for Services
116116

117-
Include {ruby Async::Service::ContainerEnvironment} for services that run in containers using {ruby Async::Service::ContainerService}:
117+
Include {ruby Async::Service::Managed::Environment} for services that need robust lifecycle management using {ruby Async::Service::Managed::Service}:
118118

119119
```ruby
120120
module WebEnvironment
121-
include Async::Service::ContainerEnvironment
121+
include Async::Service::Managed::Environment
122122

123123
def service_class
124124
WebService
@@ -199,16 +199,16 @@ end
199199

200200
## Service Best Practices
201201

202-
### Use ContainerService as Base Class
202+
### Use `Managed::Service` as Base Class
203203

204-
Prefer `Async::Service::ContainerService` over `Generic` for most services:
204+
Prefer `Async::Service::Managed::Service` over `Generic` for most services:
205205

206206
```ruby
207-
class WebService < Async::Service::ContainerService
208-
# ContainerService automatically handles:
207+
class WebService < Async::Service::Managed::Service
208+
# Managed::Service automatically handles:
209209
# - Container setup with proper options.
210210
# - Health checking with process title updates.
211-
# - Integration with Formatting module.
211+
# - Preloading of scripts before startup.
212212

213213
private def format_title(evaluator, server)
214214
# Customize process title display
@@ -247,7 +247,7 @@ Try to keep process titles short and focused.
247247
Utilize the `start` and `stop` hooks to manage shared resources effectively:
248248

249249
```ruby
250-
class WebService < Async::Service::ContainerService
250+
class WebService < Async::Service::Managed::Service
251251
def start
252252
# Bind to the endpoint in the container:
253253
@endpoint = @evaluator.endpoint.bind
@@ -261,6 +261,8 @@ class WebService < Async::Service::ContainerService
261261
end
262262
```
263263

264+
These hooks are invoked **before** the container is setup (e.g. pre-forking).
265+
264266
## Testing Best Practices
265267

266268
### Test Environments in Isolation

‎guides/service-architecture/readme.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,8 @@ end
262262

263263
### Health Checking
264264

265+
For services using `Async::Service::Managed::Service`, health checking is handled automatically. For services extending `Generic`, you can set up health checking manually:
266+
265267
```ruby
266268
def setup(container)
267269
container_options = @evaluator.container_options
@@ -270,7 +272,7 @@ def setup(container)
270272
container.run(**container_options) do |instance|
271273
# Prepare your service.
272274

273-
Sync do
275+
Async do
274276
# Start your service.
275277

276278
# Set up health checking, if a timeout was specified:
@@ -282,6 +284,8 @@ def setup(container)
282284
end
283285
```
284286

287+
Note: `Async::Service::Managed::Service` automatically handles health checking, container options, and process title formatting, so you typically don't need to set this up manually.
288+
285289
## How They Work Together
286290

287291
The four layers interact in a specific pattern:
@@ -435,23 +439,21 @@ configuration = Async::Service::Configuration.load(["config/web.rb", "config/wor
435439
Create reusable configuration modules:
436440

437441
```ruby
438-
module ContainerEnvironment
442+
module ManagedEnvironment
443+
include Async::Service::Managed::Environment
444+
439445
def count
440446
4
441447
end
442448

443-
def restart
444-
true
445-
end
446-
447449
def health_check_timeout
448450
30
449451
end
450452
end
451453

452454
configuration = Async::Service::Configuration.build do
453455
service "my-service" do
454-
include ContainerEnvironment
456+
include ManagedEnvironment
455457
service_class MyService
456458
end
457459
end

‎readme.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
3030
### Unreleased
3131

3232
- Rename `ContainerEnvironment` and `ContainerService` to `Managed::Environment` and `Managed::Service` respectively.
33+
- Health check uses `Fiber.new{instance.ready!}.resume` to confirm fiber allocation is working.
3334

3435
### v0.14.4
3536

0 commit comments

Comments
 (0)