From 795c2cf819c76121d23c3dfecfec33f20f13d3d5 Mon Sep 17 00:00:00 2001 From: Gus Eggert Date: Sat, 13 Aug 2022 08:08:52 -0400 Subject: [PATCH] docs: add fx plugin documentation to plugins.md (#9191) --- core/builder.go | 2 ++ docs/plugins.md | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/core/builder.go b/core/builder.go index af6ee4c7b0d..aacb51884bd 100644 --- a/core/builder.go +++ b/core/builder.go @@ -16,6 +16,8 @@ import ( ) // FXNodeInfo contains information useful for adding fx options. +// This is the extension point for providing more info/context to fx plugins +// to make decisions about what options to include. type FXNodeInfo struct { FXOptions []fx.Option } diff --git a/docs/plugins.md b/docs/plugins.md index 1c321300481..1feca834c0c 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -48,6 +48,28 @@ application without IPC and without forking Kubo. Note: We eventually plan to make Kubo usable as a library. However, this plugin type is likely the best interim solution. +### fx (experimental) + +Fx plugins let you customize the [fx](https://pkg.go.dev/go.uber.org/fx) dependency graph and configuration, +by customizing the`fx.Option`s that are passed to `fx` when the IPFS node is initialized. + +For example, you can inject custom implementations of interfaces such as [exchange.Interface](https://github.com/ipfs/go-ipfs-exchange-interface) +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))))`. + +Fx supports some advanced customization. Simple interface replacements like above are unlikely to break in the future, +but the more invasive your changes, the more likely they are to break between releases. Kubo cannot guarantee backwards +compatibility for invasive `fx` customizations. + +Fx options are applied across every execution of the `ipfs` binary, including: + +- Repo initialization +- Daemon +- Applying migrations +- etc. + +So if you plug in a blockservice that disallows non-allowlisted CIDs, then this may break migrations +that fetch migration code over IPFS. + ### Internal (never stable)