hephaestus 0.8.12.2 → 0.8.13
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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +7 -0
- data/README.md +0 -174
- data/lib/hephaestus/generators/app_generator.rb +3 -29
- data/lib/hephaestus/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: f10ca0de88c450f5e8febca532d785bb3e0b9ae1392e84a89e5bc69822936bf4
|
4
|
+
data.tar.gz: 5558246e1b43416722c74d86f35527b39894834524bb863c9cc7380233b661c5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c38a22b9ac3409157e42f26aea6b82ea3b488c984b43e18918c8d4cf12aee16ec446fad81aa0d04cecad9ad5676130e4cc0990605d8502f2131af37e3d44d152
|
7
|
+
data.tar.gz: 04aa1224bad239a6f7ef662d1f00a61ffb0a560ab882472e7afcad07f820600f7f3e6f2aa70ef639338abfa5264f6544b99e096f75f0b4922c79425a77598ed9
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,10 @@
|
|
1
|
+
# [v0.8.13] - 17-12-2024
|
2
|
+
## What's Changed
|
3
|
+
* Move content to clio by @gjtorikian in https://github.com/yettoapp/hephaestus/pull/99
|
4
|
+
* Remove outro, point to Clio by @gjtorikian in https://github.com/yettoapp/hephaestus/pull/100
|
5
|
+
|
6
|
+
|
7
|
+
**Full Changelog**: https://github.com/yettoapp/hephaestus/compare/v0.8.12.2...v0.8.13
|
1
8
|
# [v0.8.12.2] - 17-12-2024
|
2
9
|
## What's Changed
|
3
10
|
* Fixups by @gjtorikian in https://github.com/yettoapp/hephaestus/pull/97
|
data/README.md
CHANGED
@@ -33,180 +33,6 @@ This way you can wipe the dir and quickly iterate on new changes.
|
|
33
33
|
|
34
34
|
If you're having trouble connecting to the Internet, you can set `HEPHAESTUS_NO_EXTERNAL=1`.
|
35
35
|
|
36
|
-
## Building upon the base
|
37
|
-
|
38
|
-
Most of the files which Hephaestus creates for you shouldn't need much modification. The information below is part-informative, part-guidelines on how to extend the generated code for your specific plug.
|
39
|
-
|
40
|
-
### Controllers
|
41
|
-
|
42
|
-
#### `ApplicationController`
|
43
|
-
|
44
|
-
Your application controller inherits from `Hephaestus::ApplicationController`, and handles the basics of request/response cycles. Two common callbacks to add here are:
|
45
|
-
|
46
|
-
- `before_action :set_request_span_context`, which lets you add data to the `OpenTelemetry` trace before a request occurs
|
47
|
-
- `after_action :set_response_span_context`, similarly, lets you add to the trace after the response is sent
|
48
|
-
|
49
|
-
For examples on how to integrate with these, check out `plug-email`.
|
50
|
-
|
51
|
-
#### `SettingsController`
|
52
|
-
|
53
|
-
Typically, your settings inherit directly from Hephaestus. We'll discuss more about how this works in `routes.rb`. Either way, you'll define two files:
|
54
|
-
|
55
|
-
- `app/views/settings/new.json.jbuilder`
|
56
|
-
- `app/views/settings/edit.json.jbuilder`
|
57
|
-
|
58
|
-
Define the settings UI in these files. See `plug-email` for an example of a settings page with no customizations.
|
59
|
-
|
60
|
-
However, for multi-step plugs, it's common to expect customized steps. If you'd like to extend the settings controller, create a file with one of two methods:
|
61
|
-
|
62
|
-
- `new`
|
63
|
-
- `edit`
|
64
|
-
|
65
|
-
You only need to define these methods if you're actually overriding the action—often, this only means `edit`. If you do define methods in this controller, remember to add `before_action :ensure_json_request` at the top. For examples on settings pages which have _some_ customization, see `plug-github` and `plug-linear`. For an example of a totally custom settings page, see `plug-zendesk`.
|
66
|
-
|
67
|
-
#### `AppController`
|
68
|
-
|
69
|
-
The logic to communicate with your platform sits in `AppController`. Every plug is unique, so the requirements for your platform varies!
|
70
|
-
|
71
|
-
At a minimum, though, you should place all the logic which authenticates requests in the `Authable` concern. See `plug-github` and `plug-linear` for practical examples.
|
72
|
-
|
73
|
-
#### `YettoController`
|
74
|
-
|
75
|
-
Place the logic which receives webhooks from Yetto in the `YettoController`. This controller must `include Hephaestus::ValidatesFromYetto`, and must define `before_action :from_yetto?`. Beyond that, you can respond to events as they come in, and fire jobs to perform the actions your platform needs to integrate with Yetto.
|
76
|
-
|
77
|
-
### Jobs
|
78
|
-
|
79
|
-
Jobs are at the heart of plugs, because they perform time-sensitive work asynchronously. Since Hephaestus already creates an `ApplicationJob` which inherits from `Hephaestus::ApplicationJob`, there isn't much else you need to do, other than define your jobs.
|
80
|
-
|
81
|
-
Whenever you need to integrate with Yetto, just pass the appropriate arguments to `Hephaestus::UpdateYettoJob`.
|
82
|
-
|
83
|
-
The bulk of your plug logic should exist within these jobs. Keep the controllers as place to authenticate incoming requests and respond with appropriate status codes.
|
84
|
-
|
85
|
-
### Constants
|
86
|
-
|
87
|
-
Place any and all constants in the file called `lib/constants.rb`.
|
88
|
-
|
89
|
-
Note that Hepheastus provides several convenience methods and constants for you. These are:
|
90
|
-
|
91
|
-
- `plug_shortname`: the downcased version of the plug (e.g., `Slack => slack`, `GitHub => github`)
|
92
|
-
- `plug_name`: The proper name of the plug (e.g., `Slack`, `GitHub`)
|
93
|
-
- `plug_url`: The plug's URL (e.g., `email{.plugs.yetto.app,.plugs.yetto.dev,.ngrok.io}`)
|
94
|
-
|
95
|
-
### Application Configuration
|
96
|
-
|
97
|
-
The typical Rails' environment configs (`config/environments/{development.rb,test.rb,production.rb}`) are managed by Hephaestus. However, any plug can define their own environment files as well. These are added after Hephaestus' default configuration.
|
98
|
-
|
99
|
-
The `test.rb` file in `plug-email` provides an example of this.
|
100
|
-
|
101
|
-
#### Upgrading Rails
|
102
|
-
|
103
|
-
Upgrading Rails always introduces breaking changes, even between minor releases. To ensure that a plug still works after a Rails upgrade, first, add
|
104
|
-
|
105
|
-
```ruby
|
106
|
-
rails "x"
|
107
|
-
```
|
108
|
-
|
109
|
-
to your plug's Gemfile (where `"x"` is the new Rails version.) Note that this means plugs can run Rails versions independently of what Hephaestus provides (although variance is not recommended, it can help during the upgrade process).
|
110
|
-
|
111
|
-
Next, call `rails app:update:configs`. You can pretty much ignore every changed file, except the one that starts with `new_framework_defaults_`. Use these values to slowly reintroduce the new configuration changes, as described in [the Rails documentation](https://guides.rubyonrails.org/v8.0/upgrading_ruby_on_rails.html#configure-framework-defaults).
|
112
|
-
|
113
|
-
### Integrating the Plug with the Engine
|
114
|
-
|
115
|
-
There are certain times where the child application needs to "inject" data into Hephaestus. These are typically customizations that are unique to the plug. Place these customizations in `config/application.rb`, inside of an `initializer :engines_blank_point do` block.
|
116
|
-
|
117
|
-
At a minimum, you'll need to define your plug's API version, and the version of the Yetto API it's communicating with:
|
118
|
-
|
119
|
-
```ruby
|
120
|
-
initializer :engines_blank_point do
|
121
|
-
config.yetto_api_version = "2023-03-06"
|
122
|
-
config.plug_api_version = "2023-03-06"
|
123
|
-
end
|
124
|
-
```
|
125
|
-
|
126
|
-
You can also define several other customizations:
|
127
|
-
|
128
|
-
- `config.tracing_body_filters`: use this to scrub out any sensitive data coming in from your platform, to prevent it from leaking in our metrics aggregator. See the override in `plug-email` for an example. The default is to simply log everything (after running it through [Rails' `ParameterFilter`](https://api.rubyonrails.org/v7.1/classes/ActiveSupport/ParameterFilter.html), of course), which may not be a good idea!
|
129
|
-
- `config.enhance_update_yetto_job`: use this to include any plug-specific logic which needs to occur as part of issuing calls to the Yetto API
|
130
|
-
|
131
|
-
For an example of both these customizations, see `plug-email`.
|
132
|
-
|
133
|
-
There's also middleware you can use to protect any endpoint with an OpenAPI schema. To do so, add:
|
134
|
-
|
135
|
-
```ruby
|
136
|
-
require "hephaestus/middleware/openapi_validation"
|
137
|
-
config.middleware.use(Hephaestus::Middleware::OpenapiValidation, match_path: "/app/2023-03-06/path/", limit_methods_to: ["POST"], spec: Rails.root.join("lib/schemas/path/2023-03-06/openapi.json"))
|
138
|
-
```
|
139
|
-
|
140
|
-
In this example, any `POST` to `match_path` is protected by the OpenAPI `spec` provided.
|
141
|
-
|
142
|
-
### Services
|
143
|
-
|
144
|
-
Place any HTTP communication necessary to communicate with your platform in this directory. All other code should which communicates to your plug should rely on methods defined in this file.
|
145
|
-
|
146
|
-
See any of the plugs for an example of how to define this interaction, particularly with `httpsensible`.
|
147
|
-
|
148
|
-
### Routes
|
149
|
-
|
150
|
-
If you do not have any custom actions to perform in the settings controller, define your settings pages as:
|
151
|
-
|
152
|
-
```ruby
|
153
|
-
# you must always include this line when referring to `hephaestus_settings`
|
154
|
-
HephaestusSettingsController = Hephaestus::SettingsController
|
155
|
-
|
156
|
-
get "/api/#{Rails.application.config.plug_api_version}/settings", to: "hephaestus_settings#new"
|
157
|
-
get "/api/#{Rails.application.config.plug_api_version}/settings/:organization_id/:inbox_id/:plug_installation_id/edit", to: "hephaestus_settings#edit"
|
158
|
-
```
|
159
|
-
|
160
|
-
Otherwise, be sure to refer to `hephaestus_settings` only for any default settings related actions:
|
161
|
-
|
162
|
-
```ruby
|
163
|
-
# you must always include this line when referring to `hephaestus_settings`
|
164
|
-
HephaestusSettingsController = Hephaestus::SettingsController
|
165
|
-
|
166
|
-
get "/api/#{Rails.application.config.plug_api_version}/settings", to: "hephaestus_settings#new"
|
167
|
-
get "/api/#{Rails.application.config.plug_api_version}/settings/:organization_id/:inbox_id/:plug_installation_id/edit", to: "settings#edit"
|
168
|
-
```
|
169
|
-
|
170
|
-
Otherwise, you can add any other routes your plug needs to `config/routes.rb`.
|
171
|
-
|
172
|
-
### Launching the server
|
173
|
-
|
174
|
-
First, you'll note that you have a `script/ngrok` file, which launches an ngrok server at `https://${hostname}-plug-app.ngrok.io`, which maps locally to `http://localhost:6661`. Setting up ngrok can be essential when testing the platform locally for the first time. (Keep in mind that you still need to run `script/server` to actually start the local server—this is just to help facilitate communication with the platform.)
|
175
|
-
|
176
|
-
### Setting up routes
|
177
|
-
|
178
|
-
You should probably open up config/routes.rb to make modifications to any incoming (from the platform) or outgoing (for Yetto) HTTP flows.
|
179
|
-
|
180
|
-
### Defining settings
|
181
|
-
|
182
|
-
Next, you'll want to open `app/views/settings/new.json.jbuilder` and modify the JSON structure of the Settings form page users will see when they first install the plug. Note that this adheres to a strict schema.
|
183
|
-
|
184
|
-
### Accepting events
|
185
|
-
|
186
|
-
After a user submits a plug installation on the Yetto side, it'll send a POST payload to `/api/:version/:event/:record_type`--for example, `/api/2023-03-06/after/plug_installation`. Open up the `yetto_controller.rb` file and decide what happens next!
|
187
|
-
|
188
|
-
### Creating services
|
189
|
-
|
190
|
-
Any code which communicates with the third party should be placed in the `app/services` directory. A generic HTTP service is included.
|
191
|
-
|
192
|
-
### Writing tests
|
193
|
-
|
194
|
-
In addition to writing tests for your plug interacting with its platform, many of your tests will also need to cover your plug's interaction with Yetto.
|
195
|
-
|
196
|
-
Writing these tests well comes with time; it's not an easy thing to cover in a pithy paragraph. Regardless, here's a bit of hopefully helpful advice.
|
197
|
-
|
198
|
-
Be sure to tests requests before _and_ after they occur. Typically, this takes the form of a `stub_request` and `assert_requested`. Similarly, be sure to:
|
199
|
-
|
200
|
-
- `include Hephaestus::Webmocks::SlackWebmock` whenever a plug action is expected to error out to Slack
|
201
|
-
- `include Hephaestus::Webmocks::YettoWebmock` whenever a plug needs to issue a request to Yetto
|
202
|
-
|
203
|
-
Use `include Hephaestus::API::TestHelpers` whenever you need to write a test which either
|
204
|
-
|
205
|
-
- match `"/#{plug_shortname}` routes (by issuing calls to `plug`). These are routes which your external server is calling into.
|
206
|
-
- match `/api` routes (by issuing calls to `api`). These are routes which Yetto is calling into.
|
207
|
-
|
208
|
-
For examples on when and how to use these methods, see `plug-github`.
|
209
|
-
|
210
36
|
## Acknowledgements
|
211
37
|
|
212
38
|
The template generation for this project was heavily based on [thoughtbot/suspenders](https://github.com/thoughtbot/suspenders).
|
@@ -247,37 +247,11 @@ module Hephaestus
|
|
247
247
|
def outro
|
248
248
|
say(<<~OUTPUT)
|
249
249
|
|
250
|
-
#{set_color("Congratulations!
|
250
|
+
#{set_color("Congratulations! You just made a Yetto plug.", :green)}
|
251
251
|
|
252
|
-
You'll need to `cd #{
|
252
|
+
You'll need to `cd #{shell.base.result_dir}` and run some more commands--I can't do it for you!
|
253
253
|
|
254
|
-
|
255
|
-
|
256
|
-
#{set_color("WAIT!", :red)} After running this command, note that Rails credited a file called development.key in the config/credentials directory.
|
257
|
-
Store this in 1Password, then change the .env file to use this value. Generate keys for staging/production, too:
|
258
|
-
|
259
|
-
* `bin/rails credentials:edit --environment staging`
|
260
|
-
`bin/rails credentials:edit --environment production`
|
261
|
-
|
262
|
-
Store this in 1Password too; you don't need the .env file for staging/production.
|
263
|
-
|
264
|
-
For `YETTO_SIGNING_SECRET` and `YETTO_PLUG_ID`, you'll need to generate those values yourself.
|
265
|
-
|
266
|
-
Then, try running `bin/rails c` to ensure that everything was set up correctly.
|
267
|
-
Running `rake test` is also a good idea.
|
268
|
-
|
269
|
-
#{set_color("Also, after pushing to GitHub:", :yellow)}
|
270
|
-
|
271
|
-
* Set `settings/branches` to protect `production`
|
272
|
-
* ✅ Require status checks to pass before merging
|
273
|
-
* 🖊️ Status checks that are required: `ruby / test_without_services`, `docker / test-build`, `ruby / brakeman`, `ruby / bundle-audit`.
|
274
|
-
|
275
|
-
You can only set those 👆 after you've opened the first PR on GitHub. Crazy, I know!!
|
276
|
-
But, doing so is *essential* for automerge to function properly.
|
277
|
-
|
278
|
-
* In `/settings`:
|
279
|
-
* ✅ Allow auto-merge
|
280
|
-
* ✅ Automatically delete head branches
|
254
|
+
Check out the appropriate documentation on Clio for more information: engineering/plugs/building.md
|
281
255
|
OUTPUT
|
282
256
|
end
|
283
257
|
|
data/lib/hephaestus/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: hephaestus
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.8.
|
4
|
+
version: 0.8.13
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Garen Torikian
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2024-12-
|
11
|
+
date: 2024-12-18 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bootsnap
|