2019-05-24 00:16:47 -05:00
|
|
|
===============================================================================
|
2019-06-19 12:01:18 -05:00
|
|
|
CL-IPFS-API²
|
2019-05-24 00:16:47 -05:00
|
|
|
===============================================================================
|
|
|
|
|
|
|
|
|
|
:cl-ipfs-api² is a pretty simple set of IPFS bindings for Common Lisp, using
|
2019-06-18 12:45:31 -05:00
|
|
|
the HTTP API for (almost) everything, except for pubsub (which uses the locally
|
|
|
|
|
installed go-ipfs program).
|
|
|
|
|
It uses Dexador, YASON, and UIOP.
|
2019-05-24 00:16:47 -05:00
|
|
|
|
|
|
|
|
|
2019-06-06 19:13:15 -05:00
|
|
|
————————————————————————————————————————
|
2019-05-24 00:16:47 -05:00
|
|
|
USAGE
|
2019-06-06 19:13:15 -05:00
|
|
|
————————————————————————————————————————
|
2019-07-21 22:25:14 -05:00
|
|
|
:cl-ipfs-api² is available on Quicklisp, so just run:
|
|
|
|
|
> (ql:quickload :cl-ipfs-api2)
|
2019-05-24 00:16:47 -05:00
|
|
|
|
|
|
|
|
Then you can do things like:
|
|
|
|
|
> (ipfs:add #p"~/.bashrc")
|
|
|
|
|
"QmZweanA1JRNio6DKnPN6yECWCrxmWqqG7WWUNtyuji9hZ"
|
|
|
|
|
|
|
|
|
|
> (ipfs:cat "/ipns/ipfs.io/index.html")
|
|
|
|
|
"<!DOCTYPE html>
|
|
|
|
|
……"
|
|
|
|
|
|
|
|
|
|
Most commands available are one-to-one with their API/cli counter-parts,
|
|
|
|
|
with a few notable exceptions:
|
2019-06-18 12:45:31 -05:00
|
|
|
* #'dl (counter-part to the /get call. the name is different, so
|
|
|
|
|
as to not conflict with #'common-lisp:get)
|
2019-05-24 00:16:47 -05:00
|
|
|
|
|
|
|
|
The calls implemented so far:
|
2019-06-18 12:45:31 -05:00
|
|
|
* root (cat, add, id, ls, resolve, etc)
|
|
|
|
|
* bitswap, block, bootstrap
|
|
|
|
|
* cid, config (config, config/show)
|
|
|
|
|
* dag, dht, diag
|
|
|
|
|
* file, files, filestore
|
|
|
|
|
* key, name, object
|
|
|
|
|
* p2p, pin, pubsub
|
2019-06-19 12:01:18 -05:00
|
|
|
* refs, repo, stats
|
|
|
|
|
* swarm, urlstore
|
2019-06-18 12:45:31 -05:00
|
|
|
* version (version, version/deps)
|
2019-05-24 00:16:47 -05:00
|
|
|
|
2019-06-18 12:45:31 -05:00
|
|
|
Some calls were skipped over, but wouldn't be hard to add:
|
|
|
|
|
* object/put, object/set-data object/patch/append-data
|
2019-06-19 12:01:18 -05:00
|
|
|
* tar calls were deliberately ignored (useless)
|
2019-06-18 12:45:31 -05:00
|
|
|
|
|
|
|
|
Functions return either strings, lists, or associative lists, depending on
|
|
|
|
|
context. All errors return two values— nil and an error message (string).
|
2019-06-19 12:01:18 -05:00
|
|
|
|
|
|
|
|
Make sure to read docstrings for specific information, and keeping the API
|
|
|
|
|
reference handy is a good idea (/ipns/docs.ipfs.io/reference/api/http/).
|
|
|
|
|
|
2019-06-19 15:17:52 -05:00
|
|
|
————————————————————
|
|
|
|
|
USEFUL VARIABLES
|
|
|
|
|
————————————————————
|
|
|
|
|
There are three exported variables:
|
|
|
|
|
ipfs:*api-host* → "http://127.0.0.1:5001"
|
|
|
|
|
ipfs:*api-root* → "/api/v0/"
|
|
|
|
|
ipfs:*ipfs-root* → NIL
|
|
|
|
|
|
|
|
|
|
*api-host* is the protocol, host, and port of the API server— unless you're
|
|
|
|
|
using a custom port or remote server, this probably won't need to change.
|
|
|
|
|
*api-root* is the URL root of all API calls on the server— only changes under
|
|
|
|
|
very strange circumstances.
|
|
|
|
|
*ipfs-root* is the “root” of the local IPFS daemon. This is only used with
|
|
|
|
|
the pubsub commands, since they actually invoke the local `ipfs` program.
|
|
|
|
|
You only need to change this variable if your $IPFS_PATH is irregular, like
|
|
|
|
|
"/var/ipfs/" or something weird like that.
|
|
|
|
|
|
|
|
|
|
————————————————————
|
2019-06-18 12:45:31 -05:00
|
|
|
PUBSUB USAGE
|
2019-06-19 15:17:52 -05:00
|
|
|
————————————————————
|
2019-06-18 12:45:31 -05:00
|
|
|
Pubsub usage here is such an abberation that it warrants its own section.
|
|
|
|
|
Since there isn't a (functional) HTTP API for pubsub yet, we're using the
|
|
|
|
|
actual go-ipfs program from your computer.
|
|
|
|
|
|
|
|
|
|
If you don't have go-ipfs locally installed, it won't work.
|
|
|
|
|
If you are using Windows, or anything but *nix, it probably won't work.
|
|
|
|
|
If you haven't enabled pubsub (--enable-pubsub-experiment argument to daemon),
|
|
|
|
|
it won't work.
|
|
|
|
|
|
|
|
|
|
You can sub to a topic with, ofc, #'pubsub-sub, which will return a
|
|
|
|
|
UIOP-originated process-info stream— while the `ipfs pubsub sub` command runs
|
|
|
|
|
in the background.
|
|
|
|
|
|
|
|
|
|
This stream can't be directly #'read-char or #'listen with, which is exactly
|
|
|
|
|
what you wanna do— instead, running #'uiop/launch-program:process-info-output
|
|
|
|
|
on it is necessary to expose a usable stream.
|
|
|
|
|
|
|
|
|
|
To make all that easier, there's a little abstraction I added which obfuscates
|
|
|
|
|
UIOP use and is adequate shorthand:
|
|
|
|
|
* #'pubsub-sub-read-char
|
|
|
|
|
* #'pubsub-sub-listen
|
|
|
|
|
* #'pubsub-sub-process
|
|
|
|
|
* #'pubsub-sub-close
|
|
|
|
|
|
|
|
|
|
All of those operate on the original UIOP-originated process-info stream, and
|
|
|
|
|
work exactly like you'd expect.
|
|
|
|
|
The only weird, non-obvious one is probably #'pubsub-sub-process, which applies
|
|
|
|
|
#'uiop/launch-program:process-info-output— just in case you need the raw,
|
|
|
|
|
usable stream.
|
|
|
|
|
|
|
|
|
|
Anyway, with this, you can get a continuous read on what's going on with the
|
|
|
|
|
topic you're subbed to. To publish to a topic, run #'pubsub-pub with the topic
|
|
|
|
|
and data as arguments. Pretty simple.
|
|
|
|
|
|
|
|
|
|
Both #'pubsub-sub and #'pubsub-pub, being the only functions that run a shell
|
|
|
|
|
command, include an :env argument. If you supply a string as the :env argument,
|
|
|
|
|
that string will prefix the "ipfs" command— basically only useful for changing
|
|
|
|
|
something with the "env" command (like $IPFS_PATH).
|
|
|
|
|
|
|
|
|
|
Also, if you change the ipfs:*ipfs-root* variable (to the correct value of
|
|
|
|
|
$IPFS_PATH), the :env arguments (unless otherwise specified) will default to
|
|
|
|
|
"env IPFS_PATH=" + ipfs:*ipfs-root* + " > /dev/null;"
|
2019-05-24 00:16:47 -05:00
|
|
|
|
|
|
|
|
|
2019-06-06 19:13:15 -05:00
|
|
|
————————————————————————————————————————
|
2019-05-24 00:16:47 -05:00
|
|
|
BORING STUFF
|
2019-06-06 19:13:15 -05:00
|
|
|
————————————————————————————————————————
|
2021-01-10 11:01:44 -06:00
|
|
|
License is the GNU LGPLv3:
|
|
|
|
|
check COPYING.txt (/ipfs/QmR8Rnk5QdXgrXRqmgMLmG5PuHZEjujfa3rfVhPV99TLY7)
|
2019-05-24 00:16:47 -05:00
|
|
|
Author is Jaidyn Ann <jadedctrl@teknik.io>
|
2020-12-23 21:10:40 -06:00
|
|
|
Sauce is at https://git.feneas.org/detruota/cl-ipfs-api2
|
2021-01-10 11:01:44 -06:00
|
|
|
https://github.com/JadedCtrl/cl-ipfs-api2
|
