ipfs/go-ipfs-example-plugin

Demo plugin for Kubo IPFS daemon

go-ipfs-example-plugin

example plugin for Kubo

This repository contains a set of example Kubo plugins, demonstrating how to integrate external plugins into Kubo.

Packages:

• delaystore: an example datastore plugin that wraps an inner datastore in a "delayed" datastore.
• greeter: an example daemon plugin that prints "Hello!" on start and "Goodbye!" on exit.

NOTE 1: Plugins only work on Linux and MacOS at the moment. You can track the progress of this issue here: golang/go#19282. MacOS users will need to compile Kubo themselves too, as official MacOS releases of Kubo are cross-compiled and do not support loading plugins. Also, only amd64 architecture is supported.

NOTE 2: This plugin exists as an example and a starting point for new plugins. It isn't particularly useful by itself.

Building and Installing

Go plugin system is very whiny. The following constellation need to align:

• You need to be using the same Go version to compile Kubo and the plugin. Upstream releases of Kubo use whatever it says here (v0.19.10) at the time of writing.
• The dependencies in go.mod need to be exactly the same as in the Kubo version that we want the plugin to work with. In this example, the following need to be the same as in Kubo's go.mod:
  • github.com/ipfs/boxo
  • github.com/ipfs/go-datastore
  • github.com/ipfs/go-ipfs-delay
  • github.com/ipfs/kubo
• There are additional consideration with -trimpath etc (see below).
• Failure to do so will cause errors when loading the plugin.

Using official Kubo releases

As provided the plugin is designed to work with a default version (whatever is used in the go.mod file). You can use:

make build
make install

to build and install this version.

If you want to upgrade or use a different official release of Kubo:

1. go get github.com/ipfs/kubo@<version>
2. Verify boxo, datastore and other dependencies are aligned with the version of Kubo. Otherwise set the right versions manually.
3. go mod tidy.

In some cases, fully removing the second, "indirect requires" block in go.mod and running go mod tidy will fix wrong indirect requires.

Using local Kubo builds

This is more tricky.

1. Ensure full dependency alignment
2. If you are building Kubo somewhere else (on a different computer), ensure it is built using -trimpath when doing go build (i.e. go build -trimpath)
3. You may need to build the plugin using -trimpath or not, depending on how you are building the Kubo binary and where. i.e. you can use a replace directive in go.mod to point to a local version of Kubo and then it is possibly fine to build the plugin and Kubo without trimpath altogether.

If Go versions and dependencies are aligned, usually errors have to do with -trimpath stuff. You can also try -asmflags=all=-trimpath="$(GOPATH)" -gcflags=all=-trimpath="$(GOPATH)" and setting $(GOPATH) to what go env says etc. and try to get both the plugin and Kubo binaries to reference modules with exactly the same paths.

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

License

MIT

go-ipfs-example-plugin's Issues

How to use the plugin?

I want to create a plugin so I start with this example. And I have done 'make install' and restarted IPFS, how can I have a test?

ReadMe Instructions Mistake in Go Version Determination

First of all, thanks for the work on making this example plugin usable again!

There is an issue, however, in the instructions in the ReadMe, where it says:

You need to be using the same Go version to compile Kubo and the plugin. Upstream releases of Kubo use whatever it says here (v0.19.10) at the time of writing.

The provided URL doesn't always provide the correct version. On the 6th of August 2023 I tried following the instructions with the latest version of kubo (0.21.0). At that time the link in the instructions https://github.com/ipfs/distributions/blob/master/.tool-versions#L2 said golang 1.19.11, which resulted in errors when running the plugin. When running kubo in the terminal with ipfs daemon, I noticed in the console output it said Golang version: go1.19.10, so I reinstalled go with that version and then the plugin worked.

Kubo crashes when loading plugin: fatal error: runtime: no plugin module data

I want to try building my own Kubo plugin, so I tried to run this demo first. I successfully compiled and installed this project using the following commands:

git clone https://github.com/ipfs/go-ipfs-example-plugin.git
cd go-ipfs-example-plugin
make go.mod IPFS_VERSION=v0.19.0
make build
make install

But now when I start Kubo v0.19.0 with ipfs daemon, it crashes immediately. Here is an excerpt of the ouput:

fatal error: runtime: no plugin module data

goroutine 1 [running]:
runtime.throw({0x281abe7?, 0xe643bb?})
	runtime/panic.go:1047 +0x5d fp=0xc0002ff328 sp=0xc0002ff2f8 pc=0xe3387d
plugin.lastmoduleinit()
	runtime/plugin.go:20 +0x8ce fp=0xc0002ff410 sp=0xc0002ff328 pc=0xe6420e
plugin.open({0xc0007164b0, 0x2e})
	plugin/plugin_dlopen.go:77 +0x3ef fp=0xc0002ff680 sp=0xc0002ff410 pc=0x1e6918f
plugin.Open(...)
	plugin/plugin.go:32
github.com/ipfs/kubo/plugin/loader.unixLoadPlugin({0xc0007164b0?, 0xe643bb?})
	github.com/ipfs/[email protected]/plugin/loader/load_unix.go:20 +0x25 fp=0xc0002ff6f0 sp=0xc0002ff680 pc=0x2063725
github.com/ipfs/kubo/plugin/loader.loadDynamicPlugins.func1({0xc0007164b0, 0x2e}, {0x2bff608, 0xc0001f76c0}, {0x0?, 0x0?})
	github.com/ipfs/[email protected]/plugin/loader/loader.go:206 +0x1af fp=0xc0002ff7e8 sp=0xc0002ff6f0 pc=0x20646af
path/filepath.walk({0xc0007164b0, 0x2e}, {0x2bff608, 0xc0001f76c0}, 0xc0002ffa10)
	path/filepath/path.go:434 +0x123 fp=0xc0002ff8b0 sp=0xc0002ff7e8 pc=0xf18343
path/filepath.walk({0xc000512d00, 0x1c}, {0x2bff608, 0xc0001f75f0}, 0xc0002ffa10)
	path/filepath/path.go:458 +0x285 fp=0xc0002ff978 sp=0xc0002ff8b0 pc=0xf184a5
path/filepath.Walk({0xc000512d00, 0x1c}, 0xc0002ffa10)
	path/filepath/path.go:521 +0x6c fp=0xc0002ff9c8 sp=0xc0002ff978 pc=0xf1860c
github.com/ipfs/kubo/plugin/loader.loadDynamicPlugins({0xc000512d00, 0x1c})
	github.com/ipfs/[email protected]/plugin/loader/loader.go:187 +0xd9 fp=0xc0002ffa40 sp=0xc0002ff9c8 pc=0x2064499
github.com/ipfs/kubo/plugin/loader.(*PluginLoader).LoadDirectory(0xc000714f40, {0xc000512d00?, 0x3d58760?})
	github.com/ipfs/[email protected]/plugin/loader/loader.go:163 +0xc6 fp=0xc0002ffab0 sp=0xc0002ffa40 pc=0x2064306
github.com/ipfs/kubo/plugin/loader.NewPluginLoader({0xc000718438, 0x14})
	github.com/ipfs/[email protected]/plugin/loader/loader.go:115 +0x225 fp=0xc0002ffb58 sp=0xc0002ffab0 pc=0x2063c05
main.loadPlugins({0xc000718438?, 0x0?})
	github.com/ipfs/[email protected]/cmd/ipfs/main.go:56 +0x25 fp=0xc0002ffba8 sp=0xc0002ffb58 pc=0x21955c5
main.mainRet.func2({0x2bf5b18?, 0xc000714f00}, 0xc00012b5e0)
	github.com/ipfs/[email protected]/cmd/ipfs/main.go:159 +0xf4 fp=0xc0002ffc48 sp=0xc0002ffba8 pc=0x2195a54
github.com/ipfs/go-ipfs-cmds/cli.Run({0x2bf5b18?, 0xc00081ce40?}, 0x3d26d80, {0xc000052180, 0x3, 0x3}, 0x0?, 0xc00008f168?, 0xc000014020, 0x297a0c0, ...)
	github.com/ipfs/[email protected]/cli/run.go:107 +0x4d0 fp=0xc0002ffe38 sp=0xc0002ffc48 pc=0x2182e30
main.mainRet()
	github.com/ipfs/[email protected]/cmd/ipfs/main.go:194 +0x5ba fp=0xc0002fff68 sp=0xc0002ffe38 pc=0x21962fa
main.main()
	github.com/ipfs/[email protected]/cmd/ipfs/main.go:78 +0x19 fp=0xc0002fff80 sp=0xc0002fff68 pc=0x2195719
runtime.main()
	runtime/proc.go:250 +0x212 fp=0xc0002fffe0 sp=0xc0002fff80 pc=0xe363f2
runtime.goexit()
	runtime/asm_amd64.s:1594 +0x1 fp=0xc0002fffe8 sp=0xc0002fffe0 pc=0xe69901

The full output is in the file attatched.
KuboPluginCrash.txt

I looked around online and found a few posts in other projectds' forums about similar errors, but as this is basically my first time working with the go language I do not have the ability to figure out what is going wrong.

Platform:
x86_64 GNU/Linux

Can't set target IPFS_VERSION=v0.20.0

I want to try building my own Kubo plugin, so I tried to run this demo first.
Sadly, already the first step of setting the IPFS_VERSION to compile against fails when I try to use the latest version of Kubo (v0.20.0 at the time of writing).

git clone https://github.com/ipfs/go-ipfs-example-plugin.git
cd go-ipfs-example-plugin
make go.mod IPFS_VERSION=v0.20.0

I get the following output:

./set-target.sh v0.20.0
panic: internal error: can't find reason for requirement on github.com/lucas-clemente/[email protected]

goroutine 1 [running]:
cmd/go/internal/modget.(*resolver).updateBuildList.func1({{0xc0010298c0, 0x21}, {0xc0007b6b10, 0x7}})
        /snap/go/current/src/cmd/go/internal/modget/get.go:1760 +0xd4

cmd/go/internal/modget.(*resolver).updateBuildList(0xc000184000, {0xb45d58, 0xc000032130}, {0x0, 0x0, 0x0})
        /snap/go/current/src/cmd/go/internal/modget/get.go:1765 +0x54c
cmd/go/internal/modget.(*resolver).applyUpgrades(0xc000184000, {0xb45d58, 0xc000032130}, {0x0?, 0x0, 0xc00010fd70?})
        /snap/go/current/src/cmd/go/internal/modget/get.go:1312 +0x465
cmd/go/internal/modget.runGet({0xb45d58, 0xc000032130}, 0xc00002c8d0?, {0xc0000241a0, 0x1, 0x1})
        /snap/go/current/src/cmd/go/internal/modget/get.go:351 +0x458
main.invoke(0xe5e3c0, {0xc000024190, 0x2, 0x2})
        /snap/go/current/src/cmd/go/main.go:225 +0x3d9
main.main()
        /snap/go/current/src/cmd/go/main.go:179 +0x7ce
make: *** [Makefile:26: go.mod] Error 2

This is basically my first time working with the go language I do not have the ability to figure out what is going wrong. I tried compiling against v0.19.0, and there I got a few steps further, but after downgrading Kubo and instlaling the plugin Kubo always crashed.

This package need updates following the kubo rename

This package mention and use the previous github.com/ipfs/go-ipfs.

Dependabot can't parse your go.mod

Dependabot couldn't parse the go.mod found at /go.mod.

You can mention @dependabot in the comments below to contact the Dependabot team.