Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
HACKING.md: improve formatting and fix some typos
  • Loading branch information
hhirtz authored and foxcpp committed Jan 17, 2021
1 parent be5e6a8 commit 1942484
Showing 1 changed file with 26 additions and 26 deletions.
52 changes: 26 additions & 26 deletions HACKING.md
Expand Up @@ -46,48 +46,48 @@ The function used to create a module instance is saved with this name as a key
into the global map called "modules registry".

Whenever module needs another module for some functionality, it references it
using a configuration directive with a matcher that internalls calls
modconfig.ModuleFromNode. That function looks up the module "constructor" in
using a configuration directive with a matcher that internally calls
`modconfig.ModuleFromNode`. That function looks up the module "constructor" in
the registry, calls it with corresponding arguments, checks whether the
returned module satisfies the needed interfaces and then initializes it.

Alternatively, if configuration uses &-syntax to reference existing
configuration block, ModuleFromNode simply looks it up in the global instances
configuration block, `ModuleFromNode` simply looks it up in the global instances
registry. All modules defined the configuration as a separate top-level blocks
are created before main initialization and are placed in the instances registry
where they can be looked up as mentioned before.

Top-level defined module instances are initialized (Init method) lazily as they
are required by other modules. 'smtp' and 'imap' modules follow a special
Top-level defined module instances are initialized (`Init` method) lazily as
they are required by other modules. 'smtp' and 'imap' modules follow a special
initialization path, so they are always initialized directly.

## Error handling

Familarize yourself with the github.com/foxcpp/maddy/internal/exterrors package
and make sure you have the following for returned errors:
Familiarize yourself with the `github.com/foxcpp/maddy/internal/exterrors`
package and make sure you have the following for returned errors:
- SMTP status information (smtp\_code, smtp\_enchcode, smtp\_msg fields)
- SMTP message text should contain a generic description of the error
condition without any details to prevent accidental disclosure of the
server configuration details.
- Temporary() == true for temporary errors (see exterrors.WithTemporary)
- `Temporary() == true` for temporary errors (see `exterrors.WithTemporary`)
- Field that includes the module name

The easiest way to get all of these is to use exterrors.SMTPError.
Put the original error into the Err field, so it can be inspected using
errors.Is, errors.Unwrap, etc. Put the module name into CheckName or
TargetName. Add any additional context information using the Misc field.
Note, the SMTP status code overrides the result of exterrors.IsTemporary()
for that error object, so set it using exterrors.SMTPCode that uses IsTemporary
to select between two codes.
The easiest way to get all of these is to use `exterrors.SMTPError`.
Put the original error into the `Err` field, so it can be inspected using
`errors.Is`, `errors.Unwrap`, etc. Put the module name into `CheckName` or
`TargetName`. Add any additional context information using the `Misc` field.
Note, the SMTP status code overrides the result of `exterrors.IsTemporary()`
for that error object, so set it using `exterrors.SMTPCode` that uses
`IsTemporary` to select between two codes.

If the error you are wrapping contains details in its structure fields (like
`*net.OpError`) - copy these values into Misc map, put the underlying error
object (net.OpError.Err, for example) into the Err field.
Avoid using Reason unless you are sure you can provide the error message better
than the Err.Error() or Err is nil.
`*net.OpError`) - copy these values into `Misc` map, put the underlying error
object (`net.OpError.Err`, for example) into the `Err` field.
Avoid using `Reason` unless you are sure you can provide the error message
better than the `Err.Error()` or `Err` is `nil`.

Do not attempt to add a SMTP status information for every single possible
error. Use exterrors.WithFields with basic information for errors you don't
error. Use `exterrors.WithFields` with basic information for errors you don't
expect. The SMTP client will get the "Internal server error" message and this
is generally the right thing to do on unexpected errors.

Expand All @@ -102,20 +102,20 @@ bugs will not bring the whole server down.
it altogether based on some condition.

The skeleton for the stateful check module can be found in
internal/check/skeleton.go. Throw it into a file in
`internal/check/skeleton.go`. Throw it into a file in
`internal/check/check_name` directory and start ~~breaking~~ extending it.

If you don't need any per-message state, you can use StatelessCheck wrapper.
See check/dns directory for a working example.
If you don't need any per-message state, you can use `StatelessCheck` wrapper.
See `check/dns` directory for a working example.

Here are some guidelines to make sure your check works well:
- RTFM, docs well tell you about any caveats.
- Don't share any state _between_ messages, your code will be executed in
parallel.
- Use github.com/foxcpp/maddy/check.FailAction to select behavior on check
- Use `github.com/foxcpp/maddy/check.FailAction` to select behavior on check
failures. See other checks for examples on how to use it.
- You can assume that order of check functions execution is as follows:
CheckConnection, CheckSender, CheckRcpt, CheckBody.
`CheckConnection`, `CheckSender`, `CheckRcpt`, `CheckBody`.

## Adding a modifier

Expand All @@ -125,6 +125,6 @@ Note, currently this is not possible to modify the body contents, only header
can be modified.

Structure of the modifier implementation is similar to the structure of check
implementation, check modify/replace\_addr.go for a working example.
implementation, check `modify/replace\_addr.go` for a working example.

[1]: https://github.com/foxcpp/maddy/wiki/Dev:-Comments-on-design

0 comments on commit 1942484

Please sign in to comment.