[FFmpeg-devel] [PATCH v2 1/1] avformat: Add IPFS protocol support.
Mark Gaiser
markg85 at gmail.com
Tue Feb 1 23:58:30 EET 2022
This patch adds support for:
- ffplay ipfs://<cid>
- ffplay ipns://<cid>
IPFS data can be played from so called "ipfs gateways".
A gateway is essentially a webserver that gives access to the
distributed IPFS network.
This protocol support (ipfs and ipns) therefore translates
ipfs:// and ipns:// to a http:// url. This resulting url is
then handled by the http protocol. It could also be https
depending on the gateway provided.
To use this protocol, a gateway must be provided.
If you do nothing it will try to find it in your
$HOME/.ipfs/gateway file. The ways to set it manually are:
1. Define a -gateway <url> to the gateway.
2. Define $IPFS_GATEWAY with the full http link to the gateway.
3. Define $IPFS_PATH and point it to the IPFS data path.
4. Have IPFS running in your local user folder (under $HOME/.ipfs).
Signed-off-by: Mark Gaiser <markg85 at gmail.com>
---
configure | 2 +
doc/protocols.texi | 30 +++++
libavformat/Makefile | 2 +
libavformat/ipfsgateway.c | 267 ++++++++++++++++++++++++++++++++++++++
libavformat/protocols.c | 2 +
5 files changed, 303 insertions(+)
create mode 100644 libavformat/ipfsgateway.c
diff --git a/configure b/configure
index 5b19a35f59..6ff09e7974 100755
--- a/configure
+++ b/configure
@@ -3585,6 +3585,8 @@ udp_protocol_select="network"
udplite_protocol_select="network"
unix_protocol_deps="sys_un_h"
unix_protocol_select="network"
+ipfs_protocol_select="https_protocol"
+ipns_protocol_select="https_protocol"
# external library protocols
libamqp_protocol_deps="librabbitmq"
diff --git a/doc/protocols.texi b/doc/protocols.texi
index d207df0b52..7c9c0a4808 100644
--- a/doc/protocols.texi
+++ b/doc/protocols.texi
@@ -2025,5 +2025,35 @@ decoding errors.
@end table
+ at section ipfs
+
+InterPlanetary File System (IPFS) protocol support. One can access files stored
+on the IPFS network through so called gateways. Those are http(s) endpoints.
+This protocol wraps the IPFS native protocols (ipfs:// and ipns://) to be send
+to such a gateway. Users can (and should) host their own node which means this
+protocol will use your local machine gateway to access files on the IPFS network.
+
+If a user doesn't have a node of their own then the public gateway dweb.link is
+used by default.
+
+You can use this protocol in 2 ways. Using IPFS:
+ at example
+ffplay ipfs://QmbGtJg23skhvFmu9mJiePVByhfzu5rwo74MEkVDYAmF5T
+ at end example
+
+Or the IPNS protocol (IPNS is mutable IPFS):
+ at example
+ffplay ipns://QmbGtJg23skhvFmu9mJiePVByhfzu5rwo74MEkVDYAmF5T
+ at end example
+
+You can also change the gateway to be used:
+
+ at table @option
+
+ at item gateway
+Defines the gateway to use. When nothing is provided the protocol will first try
+your local gateway. If that fails dweb.link will be used.
+
+ at end table
@c man end PROTOCOLS
diff --git a/libavformat/Makefile b/libavformat/Makefile
index 3dc6a479cc..4edce8420f 100644
--- a/libavformat/Makefile
+++ b/libavformat/Makefile
@@ -656,6 +656,8 @@ OBJS-$(CONFIG_SRTP_PROTOCOL) += srtpproto.o srtp.o
OBJS-$(CONFIG_SUBFILE_PROTOCOL) += subfile.o
OBJS-$(CONFIG_TEE_PROTOCOL) += teeproto.o tee_common.o
OBJS-$(CONFIG_TCP_PROTOCOL) += tcp.o
+OBJS-$(CONFIG_IPFS_PROTOCOL) += ipfsgateway.o
+OBJS-$(CONFIG_IPNS_PROTOCOL) += ipfsgateway.o
TLS-OBJS-$(CONFIG_GNUTLS) += tls_gnutls.o
TLS-OBJS-$(CONFIG_LIBTLS) += tls_libtls.o
TLS-OBJS-$(CONFIG_MBEDTLS) += tls_mbedtls.o
diff --git a/libavformat/ipfsgateway.c b/libavformat/ipfsgateway.c
new file mode 100644
index 0000000000..2b52fc9392
--- /dev/null
+++ b/libavformat/ipfsgateway.c
@@ -0,0 +1,267 @@
+/*
+ * IPFS and IPNS protocol support through IPFS Gateway.
+ * Copyright (c) 2022 Mark Gaiser
+ *
+ * This file is part of FFmpeg.
+ *
+ * FFmpeg is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * FFmpeg is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with FFmpeg; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#include "libavutil/avassert.h"
+#include "libavutil/avstring.h"
+#include "libavutil/internal.h"
+#include "libavutil/opt.h"
+#include "libavutil/tree.h"
+#include "avformat.h"
+#include <fcntl.h>
+#if HAVE_IO_H
+#include <io.h>
+#endif
+#if HAVE_UNISTD_H
+#include <unistd.h>
+#endif
+#include <sys/stat.h>
+#include <stdlib.h>
+#include "os_support.h"
+#include "url.h"
+
+typedef struct Context {
+ AVClass *class;
+ URLContext *inner;
+ char *gateway;
+} Context;
+
+// A best-effort way to find the IPFS gateway.
+// Only the most appropiate gateway is set. It's not actually requested (http call) to prevent
+// a potential slowdown in startup. A potential timeout is handled by the HTTP protocol.
+//
+// When done and the return value is 1, a potential IPFS Gateway is set in the gateway
+// variable in the inner URLContext.
+static int ff_populate_ipfs_gateway(URLContext *h)
+{
+ Context *c = h->priv_data;
+ char *home_folder;
+ char *ipfs_full_data_folder;
+ char *ipfs_gateway_file;
+ struct stat st;
+ int stat_ret = 0;
+ FILE *gateway_file;
+ char gateway_file_data[1000];
+
+ // First, test if there already is a path in c->gateway. If it is then it was provided as
+ // cli arument and should be used. It takes precdence.
+ if (c->gateway != NULL) {
+ return 1;
+ }
+
+ // Test $IPFS_GATEWAY.
+ c->gateway = getenv("IPFS_GATEWAY");
+ if (c->gateway) {
+ return 1;
+ } else {
+ av_log(h, AV_LOG_DEBUG, "$IPFS_GATEWAY is empty.\n");
+ }
+
+ // We need to know the IPFS folder to - eventually - read the contents of the "gateway" file which would tell us the gateway to use.
+ ipfs_full_data_folder = getenv("IPFS_PATH");
+
+ if (!ipfs_full_data_folder) {
+ av_log(h, AV_LOG_DEBUG, "$IPFS_PATH is empty.\n");
+
+ // Try via the home folder.
+ home_folder = getenv("HOME");
+ ipfs_full_data_folder = av_asprintf("%s/.ipfs/", home_folder);
+
+ // Stat the folder. It should exist in a default IPFS setup when run as local user.
+#ifndef _WIN32
+ stat_ret = stat(ipfs_full_data_folder, &st);
+#else
+ stat_ret = win32_stat(ipfs_full_data_folder, &st);
+#endif
+ if (stat_ret < 0) {
+ av_log(h, AV_LOG_DEBUG, "Unable to find IPFS folder. We tried:\n");
+ av_log(h, AV_LOG_DEBUG, "- $IPFS_PATH, which was empty.\n");
+ av_log(h, AV_LOG_DEBUG, "- $HOME/.ipfs (full uri: %s) which doesn't exist.\n", ipfs_full_data_folder);
+ return -1;
+ }
+ }
+
+ ipfs_gateway_file = av_asprintf("%sgateway", ipfs_full_data_folder);
+
+ // Stat the gateway file. If it doesn't exist we have no gateway. If it does, we might have one.
+#ifndef _WIN32
+ stat_ret = stat(ipfs_gateway_file, &st);
+#else
+ stat_ret = win32_stat(ipfs_gateway_file, &st);
+#endif
+ if (stat_ret < 0) {
+ av_log(h, AV_LOG_ERROR, "The IPFS gateway file (full uri: %s) doesn't exist. Is the gateway enabled?\n", ipfs_gateway_file);
+ return -1;
+ }
+
+ // Get the contents of the gateway file.
+ gateway_file = av_fopen_utf8(ipfs_gateway_file, "r");
+ if (!gateway_file) {
+ av_log(h, AV_LOG_ERROR, "Unable to open the IPFS gateway file (full uri: %s).\n", ipfs_gateway_file);
+ return -1;
+ }
+
+ fscanf(gateway_file, "%[^\n]", gateway_file_data);
+ fclose(gateway_file);
+
+ if ((st.st_size < 1) || (strlen(gateway_file_data) < 1)) {
+ av_log(h, AV_LOG_ERROR, "The IPFS gateway file (full uri: %s) appears to be empty. Is the gateway started?\n", ipfs_gateway_file);
+ return -1;
+ }
+
+ // Copy the gateway url into c->gateway.
+ c->gateway = av_asprintf("%s", gateway_file_data);
+ if (c->gateway) {
+ return 1;
+ } else {
+ av_log(h, AV_LOG_DEBUG, "Unknown error in the IPFS gateway file.\n");
+ }
+
+ return -1;
+}
+
+// For now just makes sure that the gateway ends in url we expect. Like http://localhost:8080/.
+// Explicitly with the traling slash.
+static void ff_sanitize_ipfs_gateway(URLContext *h)
+{
+ Context *c = h->priv_data;
+ const char last_gateway_char = c->gateway[strlen(c->gateway) - 1];
+
+ if (last_gateway_char != '/') {
+ c->gateway = av_asprintf("%s/", c->gateway);
+ }
+}
+
+static int translate_ipfs_to_http(URLContext *h, const char *uri, int flags, AVDictionary **options)
+{
+ const char *ipfs_cid;
+ const char *protocol_path_suffix = "ipfs/";
+ char *fulluri;
+ int ret;
+ Context *c = h->priv_data;
+ int is_ipfs = (av_strstart(uri, "ipfs://", &ipfs_cid) || av_strstart(uri, "ipfs:", &ipfs_cid));
+ int is_ipns = (av_strstart(uri, "ipns://", &ipfs_cid) || av_strstart(uri, "ipns:", &ipfs_cid));
+
+ // Populate the IPFS gateway if we have any.
+ // If not, inform the user how to properly set one.
+ if (ff_populate_ipfs_gateway(h) < 0) {
+ av_log(h, AV_LOG_ERROR, "No IPFS gateway was set. Make sure a local IPFS instance is running.\n");
+ av_log(h, AV_LOG_INFO, "There are multiple options to define this gateway. The below options are in order of precedence:\n");
+ av_log(h, AV_LOG_INFO, "1. Define a -gateway <url> to the gateway without trailing forward slash.\n");
+ av_log(h, AV_LOG_INFO, "2. Define $IPFS_GATEWAY with the full http link to the gateway without trailing forward slash.\n");
+ av_log(h, AV_LOG_INFO, "3. Define $IPFS_PATH and point it to the IPFS data path.\n");
+ av_log(h, AV_LOG_INFO, "4. Have IPFS running in your local user folder (under $HOME/.ipfs).\n");
+ av_log(h, AV_LOG_INFO, "In all path cases, a file named gateway is expected. See https://github.com/ipfs/specs/issues/261 for more information.\n");
+ ret = AVERROR(EINVAL);
+ return ret;
+ }
+
+ // Sanitize the gateway to a format we expect.
+ ff_sanitize_ipfs_gateway(h);
+
+ // We must have either ipns or ipfs.
+ if (!is_ipfs && !is_ipns) {
+ ret = AVERROR(EINVAL);
+ av_log(h, AV_LOG_ERROR, "Unsupported url %s\n", uri);
+ return ret;
+ }
+
+ // If we have IPNS, update the protocol.
+ if (is_ipns) {
+ protocol_path_suffix = "ipns/";
+ }
+
+ // Concatenate the url. This ends up with something like: http://localhost:8080/ipfs/Qm.....
+ fulluri = av_asprintf("%s%s%s", c->gateway, protocol_path_suffix, ipfs_cid);
+
+ // Pass the URL back to FFMpeg's protocol handler.
+ if ((ret = ffurl_open_whitelist(&c->inner, fulluri, flags,
+ &h->interrupt_callback, options,
+ h->protocol_whitelist, h->protocol_blacklist, h)) < 0) {
+ av_log(h, AV_LOG_ERROR, "Unable to open resource: %s\n", fulluri);
+ return ret;
+ }
+
+ return ret;
+}
+
+static int ipfs_read(URLContext *h, unsigned char *buf, int size)
+{
+ Context *c = h->priv_data;
+ int ret;
+
+ ret = ffurl_read(c->inner, buf, size);
+
+ return ret;
+}
+
+static int64_t ipfs_seek(URLContext *h, int64_t pos, int whence)
+{
+ Context *c = h->priv_data;
+ int64_t ret;
+
+ ret = ffurl_seek(c->inner, pos, whence);
+
+ return ret;
+}
+
+static int ipfs_close(URLContext *h)
+{
+ Context *c = h->priv_data;
+ int ret;
+
+ ret = ffurl_closep(&c->inner);
+
+ return ret;
+}
+
+#define OFFSET(x) offsetof(Context, x)
+
+static const AVOption options[] = {
+ {"gateway", "The gateway to ask for IPFS data.", OFFSET(gateway), AV_OPT_TYPE_STRING, {.str = NULL}, 0, 0, AV_OPT_FLAG_DECODING_PARAM },
+ {NULL},
+};
+
+static const AVClass ipfs_context_class = {
+ .class_name = "IPFS",
+ .item_name = av_default_item_name,
+ .option = options,
+ .version = LIBAVUTIL_VERSION_INT,
+};
+
+const URLProtocol ff_ipfs_protocol = {
+ .name = "ipfs",
+ .url_open2 = translate_ipfs_to_http,
+ .url_read = ipfs_read,
+ .url_seek = ipfs_seek,
+ .url_close = ipfs_close,
+ .priv_data_size = sizeof(Context),
+ .priv_data_class = &ipfs_context_class,
+};
+
+const URLProtocol ff_ipns_protocol = {
+ .name = "ipns",
+ .url_open2 = translate_ipfs_to_http,
+ .url_read = ipfs_read,
+ .url_seek = ipfs_seek,
+ .url_close = ipfs_close,
+ .priv_data_size = sizeof(Context),
+ .priv_data_class = &ipfs_context_class,
+};
diff --git a/libavformat/protocols.c b/libavformat/protocols.c
index 948fae411f..675b684bd3 100644
--- a/libavformat/protocols.c
+++ b/libavformat/protocols.c
@@ -73,6 +73,8 @@ extern const URLProtocol ff_libsrt_protocol;
extern const URLProtocol ff_libssh_protocol;
extern const URLProtocol ff_libsmbclient_protocol;
extern const URLProtocol ff_libzmq_protocol;
+extern const URLProtocol ff_ipfs_protocol;
+extern const URLProtocol ff_ipns_protocol;
#include "libavformat/protocol_list.c"
--
2.35.1
More information about the ffmpeg-devel
mailing list