Ir al contenido principal

Tutorial: Envío de archivos a IPFS mediante WSO2 EI (Parte I)

En este tutorial se explicará y ejemplificará la integración que se puede dar entre WSO2 Enterprise Integrator (WSO2 EI) y el Api de InterPlanetary File System (IPFS). Se configurará una secuencia con la cual se envíe los archivos a los servicios IPFS y se registre la entrada en una base de datos DBMS.

Este tutorial es una primera parte de una serie de dos, por lo que si quieres seguir aprendiendo, ¡no te pierdas nuestro próximo tutorial!

El índice ayudará a organizar el siguiente tutorial:

1. ¿Qué es IPFS?

IPFS, el sistema de archivos interplanetarios (InterPlanetary File System – IPFS), es un protocolo y una red diseñada para crear un método p2p (peer-to-peer) que busca conectar todos los dispositivos informáticos con el mismo sistema de archivos.

IPFS proporciona un modelo de almacenamiento en bloque de alto rendimiento y contenido direccionado.

2. Prerrequisitos

Para realizar el ejercicio se debe tener en cuenta lo siguiente:

3. Glosario

Palabra

Descripción

IPFS

InterPlanetary File System (sistema de archivos interplanetarios)

WSO2 EI

WSO2 Enterprise Integrator

RDBMS

Sistema de gestión de bases de datos relacionales

API

Application programming interface (Interfaz de Programación de Aplicaciones)

API REST

Se trata de un conjunto de principios de arquitectura cliente-servidor compuesta de clientes, servidores y recursos, con la gestión de solicitudes a través de HTTP.

RPC

Remote Procedure Call (Llamada a procedimiento remoto).

IDE

Integrated Development Environment (Entorno de Desarrollo Interactivo).

4. Instalación y configuración de IPFS en dockers

Para iniciar la instalación y posterior configuración del contenedor de IPFS se debe iniciar creando las siguientes carpetas.

  • staging → es un directorio que puede usar para almacenar archivos para el uso de la línea de comandos (como ipfs add).

  • data → es el volumen de datos se utilizara para almacenar el repositorio local de IPFS (configuración y base de datos).

Para ello se ejecutaran los siguientes comandos para staging:

mkdir </absolute/path/to/staging/>
export ipfs_staging=</absolute/path/to/staging/>

Y para data.

mkdir </absolute/path/to/data/>
export ipfs_data=</absolute/path/to/data/>

Posteriormente se ejecuta el comando para iniciar (descargar) y la imagen de IPFS, y exponer de los puertos 4001-5001-8080

docker run -d --name ipfs -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 127.0.0.1:4001:4001 -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/go-ipfs:latest

Donde:

Parámetro

Valor

Descripción

8080

-p 127.0.0.1:8080:8080

El puerto 8080 es la puerta de enlace HTTP que le permite consultar datos de IPFS con su navegador.

4001

-p 127.0.0.1:4001:4001

El puerto 4001 es el puerto de swarm que usa IPFS para comunicarse con otros nodos.

5001

-p 127.0.0.1:5001:5001

El puerto es para la API local.

Vinculando el puerto 5001 a la ip 127.0.0.1, esto para no exponer al mundo exterior el IPFS

data

-v $ipfs_data:/data/ipfs

Toma los datos de la variable ipfs_data previamente generada para montar el volumen.

staging

-v $ipfs_staging:/export

Toma los datos de la variable ipfs_staging previamente generada para montar el volumen.

ipfs:latest

ipfs/go-ipfs:latest

Nombre y versión se la imagen docker de IPFS.

Para comprobar la construcción de del contenedor de IPFS haya sido correcta, se puede ejecutar el siguiente comando.

docker logs ipfs

Con este comando se mostrará la información del contenedor recien creado.

Changing user to ipfs
ipfs version 0.8.0-rc1
generating ED25519 keypair...done
peer identity: 12D3KooWJcQVqoncvE4NJX4G77r4ecCuBLpkAtbRSLCCCfshzLUR
initializing IPFS node at /data/ipfs
to get started, enter:

    ipfs cat /ipfs/QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/readme

Initializing daemon...
go-ipfs version: 0.8.0-rc1-02d15ac
Repo version: 11
System version: amd64/linux
Golang version: go1.14.4
2020/12/28 18:43:45 failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 2048 kiB, got: 416 kiB). See https://github.com/lucas-clemente/quic-go/wiki/UDP-Receive-Buffer-Size for details.
Swarm listening on /ip4/127.0.0.1/tcp/4001
Swarm listening on /ip4/127.0.0.1/udp/4001/quic
Swarm listening on /ip4/172.17.0.3/tcp/4001
Swarm listening on /ip4/172.17.0.3/udp/4001/quic
Swarm listening on /p2p-circuit
Swarm announcing /ip4/127.0.0.1/tcp/4001
Swarm announcing /ip4/127.0.0.1/udp/4001/quic
Swarm announcing /ip4/172.17.0.3/tcp/4001
Swarm announcing /ip4/172.17.0.3/udp/4001/quic
Swarm announcing /ip4/192.141.245.27/udp/31919/quic
API server listening on /ip4/0.0.0.0/tcp/5001
WebUI: http://0.0.0.0:5001/webui
Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080
Daemon is ready

Como se puede ver en la información anterior, al crear el contenedor se crea 1 nodo de IPFS, en el cual la información relevante es:

Parámetro

Descripción

API server listening on /ip4/0.0.0.0/tcp/5001

Url que se utilizara para enlazar a otro nodos.

WebUI: http://0.0.0.0:5001/webui

Url de la consola web de IPFS.

http://127.0.0.1:5001/webui

Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080

Url del gateway que permite consultar datos al nodo de IPFS desde el navegador.

Ejemplo:

http://127.0.0.1:8080/ipfs/QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/readme

Como último paso para la configuración se debe entrar al contenedor del IPFS con el siguiente comando.

docker exec -it <container> /bin/bash

Para obtener el valor de <container> se debe ejecutar el comando.

docker ps

Con el cual se desplegará una lista con los contenedores que están corriendo en docker, la columna de CONTAINER ID mostrará el valor para dicho parámetro.

Posteriormente haber ingresado al contenedor se debe ejecutar el siguiente comando para eliminar las conexiones con los nodos predefinidos (Públicos) y con ello se trabajará con un nodo privado.

Los nodos cliente utilizan un nodo de bootstrap para conectarse a la red IPFS privada. El programa de bootstrap conecta a los clientes con otros nodos disponibles en la red. En la red privada no se puede usar el bootstrap de la red pública IPFS, por lo que se debe eliminar el bootstrap existente.

ipfs bootstrap rm --all

Para verificar el resultado de la operación anterior se ejecutará el siguiente comando. El resultado muestra el Bootstrap vacio.

ipfs config show | grep Bootstrap

Una ves comprobado el estado del contenedor de docker de IPFS, se ingresará a la url http://127.0.0.1:5001/webui para ingresar a la consola web.

De igual manera se puede verificar la configuración anterior, siguiendo los siguientes pasos:

  1. En el menú lateral izquierdo dar clic izquierdo en Configuración.

  2. En la pestaña de CONFIG IPFS, se mostrará el archivo anteriormente mencionado con la configuración de Boostrap en vacio.

5. ¿Por qué utilizar la API de IPFS?

La API de IPFS, le permite mantener conexiones entre “peer” que duran más que alguna aplicación y se puede mantener un solo nodo IPFS en ejecución en lugar de varios si la aplicación puede iniciarse varias veces.

Es preferible usar la API a incrustar IPFS directamente en un programa, ya al utilizar la API permite que si existiera una actualización en los comandos de IPFS (CLI Commannd-line), esto no afectara la operación de los servicios.

Para mayor información se puede consultar la siguiente url https://docs.ipfs.io/reference/http/api/#getting-started .

6. Códigos de estados HTTP

Los códigos de estado usados en la capa RPC son los siguientes:

Código

Descripción

200

La solicitud se procesó o se está procesando (streaming).

500

Significa que la función existe, pero IPFS no pudo cumplir con la solicitud debido a un error.

400

RPC con formato incorrecto, error de tipo de argumento, etc.

403

Llamada RPC prohibida.

404

El endpoint de RPC no existe.

405

Significa que se está utilizando el método HTTP incorrecto (es decir, GET en lugar de POST).

7. Ejemplo con API IPFS

A continuación se muestra una de las formas de utilizar el API REST de IPFS, para este ejemplo se utiliza la aplicación POSTMAN con la cual se consultará la versión de IPFS para ello se llamará al servicio /api/v0/version.

Donde la petición se compone de:

Parámetro

Valor

Descripción

Método

POST

Método HTTP para acceder al servicio.

Url

http://127.0.0.1:5001/api/v0/version

Url de la API IPFS.

En caso de éxito, la llamada a este endpoint volverá con el código 200 y el siguiente body:

Parámetro

Valor

Descripción

Version

0.8.0-rc1

Versión del IPFS.

Commit

02d15ac

Muestra el hash de commit.

Repo

11

Muestra la versión del repositorio.

System

amd64/linux

Muestra el nombre del sistema operativo.

Golang

go1.14.4

Muestra la versión de go.

Con el ejemplo anterior se procederá a realizar la validación del servicio que se integrara con WSO2 EI el cual tiene la funcionalidad para agregar archivos a IPFS, para ello se puede llamar el servicio /api/v0/add.

Donde la petición se compone de:

Parámetro

Valor

Descripción

Método

POST

Método HTTP para acceder al servicio.

Url

http://127.0.0.1:5001/api/v0/add

Url de la API IPFS.

File

file

Archivo que se ingresará en el IPFS.

En caso de éxito, la llamada a este endpoint volverá con el código 200 y el siguiente body:

Parámetro

Valor

Descripción

Name

texto4.txt

Nombre del archivo.

Hash

QmSo3nfa7vsQrsyqJ219YpQ1TYphGGh1YsQSRwdSaacahZ

Muestra el hash de referencia al archivo en el IPFS.

Size

42

Muestra el tamaño del archivo.

8. Integración de API IPFS (/api/v0/add) en WSO2 EI

Continuando con la integración del servicio de agregar archivos del API de IPFS se muestra en el siguiente diagrama.

El cual se explica de la siguiente manera, el enriquecedor (enrich) agrega al mensaje la información del archivo que se enviará, posteriormente el payloadFactory se cargará en el body el archivo y se enviará al servicio de IPFS (api/v0/add) realizándolo con el mediador call, posteriormente con el mediador filter se filtrará el estado que regreso el mediador call y mostrará en el log el resultado de la operación.

Para crear dicha integración se utilizará el WSO2 Integrator Studio (IS), para ello se debe descargar de la siguiente ruta: https://wso2.com/integration/integration-studio/

Una vez descargado el IS y después de descomprimirlo, se puede revisar la estructura que se deberá ejecutar para iniciar el IntegratorStudio como a continuación se muestra.

Posteriormente el IDE mostrará opciones cuando inicie, el cual solicitará la dirección sobre el workspace en el que trabajará.

Una vez iniciado el IDE de IntegrationStudio, este mostrará opciones para iniciar el desarrollo de una manera más eficiente.

Para iniciar la creación de un nuevo proyecto basta con darle clic en la opción del menú izquierdo New Integration Project

Posteriormente se desplegará un menú solicitando información relevante para la creación del proyecto como lo es el nombre del mismo y de sus módulos que lo compondrán.

Dando clic en el botón de Next, se mostrará otro formulario solicitando la información para la construcción del proyecto Maven, los datos son:

  1. Group Id → se sugiere que se inicie con: com.example.ipfs

  2. Artifact Id → por default es el nombre del proyecto de integración.

  3. Version → como primera versión se sugiere 1.0.0-SNAPSHOT

Como paso final, se debe dar clic en el botón de Finish, y el IDE cargará el proyecto. Como primer vistazo se mostrará el pom.xml del proyecto en el cual se visualizará la información y los módulos que se tienen el proyecto.

Revisando los módulos se puede visualizar que el modulo de Configs tiene una estructura estandar para Maven (src/main), pero con la diferencia de que la carpeta synapse-config contiene las siguientes subcarpetas.

  1. api

  2. endpoint

  3. inound-enpoints

  4. local-entries

  5. mesage-processors

  6. message-stores

  7. proxy-services

  8. sequences

  9. taks

  10. templates

Para fines de este tutorial, se creará un service proxy, por lo que se debe seguir los siguientes pasos.

  1. Dar clic derecho sobre la carpeta proxy-services dentro del modulo de demoipfsConfigs.

  2. En el menú emergente posicionarse en la opción de New.

  3. Posteriormente seleccionar la opción de Proxy Service.

Al realizar esos paso se mostrara una ventana donde se tendrá 3 opciones

  • Crear un nuevo servicio proxy (Create A New Proxy Service).

  • Importar un servicio ya existente (Import Proxy Service).

  • Generar un nuevo proxy service a partir de un WSDL (Generate Proxy Service using WSDL file).

Para fines de este tutorial, se seleccionará la primera opción (Create A New Proxy Service) y posteriormente se debe dar clic al botón de Next para continuar con la creación del nuevo proxy service, en cual se solicitará el nombre del proxy service y el tipo de transporte o transportes ha utilizar.

Para fines de este tutorial, el nuevo service proxy se llamará envio_v1_ipfs_sp esto es así por las siguientes características de nombrado:

Parámetro

Descripción

envio

Referencia al método que se integrara

v1

Referencia la versión del servicio

ipfs

Referencia al API o servicio que se integrara

sp

Acrónimo a Service Proxy

Y el transporte sera vfs (Virtual File System). Como último paso se debe dar clic en el botón de Finish y con eso concluirá la creación de un nuevo service proxy.

Como se puede observar en la imagen anterior, se muestra del lado derecho una paletas con elementos que se ocuparán como pueden ser los Mediator Logs, Mediator Enrich, Mediator Call, entre otros.

Otra manera de crear es seleccionar la opción de Source en vez de Design en la cual se puede copiar el siguiente código.

<?xml version="1.0" encoding="UTF-8"?>
<proxy name="envio_v1_ipfs-sp" startOnLoad="true" transports="vfs"
    xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <inSequence>
            <enrich>
                <source clone="true" type="body" />
                <target property="originalBody" type="property" />
            </enrich>
            <property name="messageType" scope="axis2" type="STRING" value="multipart/form-data" />
            <payloadFactory media-type="xml">
                <format>
                    <root>
                        <file filename="file" name="file" xmlns="http://org.apache.axis2/xsd/form-data">$1</file>
                    </root>
                </format>
                <args>
                    <arg evaluator="xml" expression="$ctx:originalBody" />
                </args>
            </payloadFactory>
            <header name="Content-Type" scope="transport" value="multipart/form-data" />
            <property name="messageType" scope="axis2" type="STRING" value="multipart/form-data" />
            <property name="OUT_ONLY" scope="default" type="STRING" value="false" />
            <log level="custom">
                <property name="======================== Envio de Archivo =========================" expression="$ctx:originalBody" />
            </log>
            <call blocking="true">
                <endpoint>
                    <http method="POST" uri-template="http://127.0.0.1:5001/api/v0/add" />
                </endpoint>
            </call>
            <filter regex="200" source="$axis2:HTTP_SC">
                <then>
                    <log level="full" />
                    <call-template target="file">
                        <with-param name="message" value="HELLO WORLD!!!!!!" />
                    </call-template>
                </then>
                <else>
                    <log level="full" />
                    <call-template target="file">
                        <with-param name="message" value="HELLO WORLD!!!!!!" />
                    </call-template>
                </else>
            </filter>
            <send />
        </inSequence>
        <outSequence />
        <faultSequence />
    </target>
    <parameter name="transport.PollInterval">5</parameter>
    <parameter name="transport.vfs.FileURI">file:///home/chakray/Documentos/WSO2/EI/test
    </parameter>
    <parameter name="transport.vfs.ContentType">application/octet-stream; charset="UTF-8"
    </parameter>
    <parameter name="transport.vfs.ActionAfterProcess">DELETE</parameter>
    <parameter name="transport.vfs.FileNamePattern">.*\..*</parameter>
    <parameter name="transport.vfs.Locking">disable</parameter>
</proxy>

Posteriormente se solicitará que se guarde el cambio en el archivo xml y se procederá a generar el CAR, para ello se debe seleccionar el modulo de demoipfsCompositeExporter y dar clic derecho para que se pueda desplegar en menú emergente con la opción de “Export Composite Application Project“ y se mostrará la siguiente ventana.

Donde se solicitará la siguiente información:

  1. El nombre del CAR.

  2. La versión del CAR.

  3. La ruta donde se depositara el CAR.

Posteriormente al dar clic en el botón de Next, se mostrará la lista de los artefactos que se agregan al CAR, en la cual se debe seleccionar el modulo de “demoipfsConfigs”.

Para finalizar se debe dar clic en el botón de Finish, con ello se mostrará el siguiente mensaje si el proceso finalizó con éxito.

Se puede comprobar el archivo CAR en la ruta ingresada anteriormente.

9. Instalación de CAR en WSO2 EI

Para realizar el proceso de instalación del archivo CAR, previamente creado, se debe realizar los siguientes pasos.

  • Al acceder a la consola, se mostrará el menú en el lado izquierdo en el cual en el apartado de Carbon Applications se deberá dar clic en la opción de “Add” para agregar el CAR que se ha creado previamente.

  • A continuación se mostrará un formulario donde se deberá dar clic en el botón de “Seleccionar archivo”.

  • Posteriormente se mostrará un cuadro emergente en el cual se solicitará seleccionar en la carpeta el CAR que se instalará.

  • Para finalizar en el formulario anterior se mostrará el nombre del CAR que se seleccionó, con ello se se procederá a dar clic en el botón “Upload”.

  • Si el despliegue se realizo con éxito se deberá observar 2 puntos:

1.- Mensaje de despliegue exitoso de CAR.

2.- Muestra en la lista de “Carbon Applications“.

  • De manera extra se puede observar el la lista de los services el service proxy que se creó. Para ello se debe dar clic en la opción “List“ en la apartado del menú de Services.

Para comprobar la integración de los servicios de IPFS con WSO2 EI, se podrá probar si en el file system al que si hacía referencia (/home/[absolutePath]/[absolutePath]/WSO2/EI/test) en el service proxy se coloca un archivo. Como respuesta de del servicio se muestra en el log el hash que se generó en el IPFS.

Para comprobarlo en el nodo de IPFS se puede consultar en la consola web, copiando el hash generado y buscarlo en la consola.

Para ello se pega el hash generado y en buscador se da clic en Examinar de esta manera se mostrará el documento previamente cargado.

10. Conclusiones

Como sea podido revisar en este tutorial de envío de archivos a IPFS mediante WSO2 EI, IPFS es un filesystem que encripta los documentos para su posterior exposición a la red (local) dentro de la organización, al trabajar en nodos se puede agregar “N“ nodos a la red según se requiera en el negocio.

Al integrarlo con IPFS la herramienta WSO2 EI se puede configurar para la entrega o almacenamiento garantizado de los documentos ya que por sus características se tanto fallas como errores se pueden controlar de manera eficiente.

Para concluir se muestra el esquema del flujo de operación del ejemplo.