docs: add fx plugin documentation to plugins.md (#9191)
Gus Eggert committed
Aug 13, 2022 at 08:08 UTC
795c2cf819c76121d23c3dfecfec33f20f13d3d5
2 files changed
+24
core/builder.go
+2
@@ -16,6 +16,8 @@ import (
16
)
17
18
// FXNodeInfo contains information useful for adding fx options.
19
+// This is the extension point for providing more info/context to fx plugins
20
+// to make decisions about what options to include.
21
type FXNodeInfo struct {
22
FXOptions []fx.Option
23
}
docs/plugins.md
+22
@@ -48,6 +48,28 @@ application without IPC and without forking Kubo.
48
Note: We eventually plan to make Kubo usable as a library. However, this
49
plugin type is likely the best interim solution.
50
51
+### fx (experimental)
52
+
53
+Fx plugins let you customize the [fx](https://pkg.go.dev/go.uber.org/fx) dependency graph and configuration,
54
+by customizing the`fx.Option`s that are passed to `fx` when the IPFS node is initialized.
55
+
56
+For example, you can inject custom implementations of interfaces such as [exchange.Interface](https://github.com/ipfs/go-ipfs-exchange-interface)
57
+or [pin.Pinner](https://github.com/ipfs/go-ipfs-pinner) by adding an option like `fx.Replace(fx.Annotate(customExchange, fx.As(new(exchange.Interface))))`.
58
+
59
+Fx supports some advanced customization. Simple interface replacements like above are unlikely to break in the future,
60
+but the more invasive your changes, the more likely they are to break between releases. Kubo cannot guarantee backwards
61
+compatibility for invasive `fx` customizations.
62
+
63
+Fx options are applied across every execution of the `ipfs` binary, including:
64
+
65
+- Repo initialization
66
+- Daemon
67
+- Applying migrations
68
+- etc.
69
+
70
+So if you plug in a blockservice that disallows non-allowlisted CIDs, then this may break migrations
71
+that fetch migration code over IPFS.
72
+
73
### Internal
74
75
(never stable)