guix-gnunet/include/rehash_service.h

/* rehash --- a decentralised hash<->hash store
   Copyright © 2020 Maxime Devos <maxime.devos@student.kuleuven.be>

   This file is part of rehash.

   rehash is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or (at
   your option) any later version.

   rehash 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 General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with rehash.  If not, see <http://www.gnu.org/licenses/>. */

/**
 * @author Maxime Devos
 *
 * @file
 * Save hash->hash mappings in the data store
 * API that can be used to store hash -> hash mappings on a GNUnet node.
 * It is backed by the data store.
 */

#ifndef REHASH_SERVICE_H
#define REHASH_SERVICE_H

#include <gnunet/gnunet_fs_service.h>
#include "rehash_types.h"

#ifdef __cplusplus
extern "C"
{
#if 0
}
#endif
#endif

/**
 * Context to control hash->hash searches.
 */
struct REHASH_QueryContext;
/**
 * Context to control hash->hash inserts.
 */
struct REHASH_StoreContext;

/* TODO: perhaps some monitoring
   and enumeration? */

/**
 * Handle to the rehash service.
 */
struct REHASH_Handle;

/**
 * Connect to the rehash service.
 *
 * If the connection failed (e.g. because the service isn't up yet),
 * a usable handle is returned anyway, and put / get requests
 * will be queued until the appropriate services are up.
 *
 * The scheduler has to be running while using the functions
 * defined here.
 *
 * @param cfg configuration to use
 * @return handle to use to access the service
 */
struct REHASH_Handle *
REHASH_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);

/**
 * Disconnect from the rehash service.
 *
 * The handle @a h will be freed, as well as
 * all associated queries and stores.
 * @param h handle to the rehash service
 */
void
REHASH_disconnect (struct REHASH_Handle *h);

/**
 * Check if @a h is connected to the rehash service.
 *
 * @param h handle to the rehash service
 * @return #GNUNET_OK if connected,
 *  #GNUNET_NO or #GNUNET_SYSERR otherwise
 */
int
REHASH_connected (struct REHASH_Handle *h);

/**
 * If @a h isn't connected yet / anymore to the rehash service,
 * retry. Otherwise a no-op.
 *
 * @param h handle to the rehash service
 */
void
REHASH_retry_connect (struct REHASH_Handle *h);

/**
 * Callback to call when a hash->hash mapping has been inserted.
 * The store context has been freed by now.
 *
 * @param cls closure
 */
typedef void
(*REHASH_StoreContinuation) (void *cls);

/**
 * Where has the hash->hash mapping been found?
 * More locations may be defined later.
 * TODO is this useful?
 */
enum REHASH_Origin
{
  REHASH_ORIGIN_DHT = 0,
  REHASH_ORIGIN_DATASTORE = 1,
};

/**
 * Callback to call when a hash->hash mapping has been found
 *
 * The found hash may have a bogus length for its type,
 * and incorrect hash->hash mappings can be found.
 *
 * @param cls closure
 * @param exp when will this value expire
 * @param origin where has this mapping been found
 * @param out_length size of @a out_hash
 * @param out_hash hash found
 */
typedef void
(*REHASH_QueryContinuation) (void *cls,
			     struct GNUNET_TIME_Absolute exp,
			     enum REHASH_Origin origin,
			     size_t out_length,
			     const char *out_hash);

/**
 * Store an hash->hash mapping into the data store
 * (and DHT, anonymity permitting), to be shared with
 * other peers. If the entry is already present, the old
 * entry is considered faulty and is replaced with the
 * new mapping.
 *
 * The store context will be freed upon success,
 * and then the callback @var{cont} is called once.
 *
 * @param h handle to the rehash store
 * @param options anonymity, replication, ... options
 * @param in_type type of hash to query with
 * @param out_type type of hash to search for
 * @param input hash to search with
 * @param input_length length of @a input_hash
 * @param output hash to find
 * @param output_length length of @a output_hash
 * @param cont continuation to call when done
 * @param cont_cls closure for @a cont
 * @return handle to abort the request
 */
struct REHASH_StoreContext *
REHASH_store_start (struct REHASH_Handle *h,
		    const struct GNUNET_FS_BlockOptions *options,
		    enum REHASH_Hash_Type in_type,
		    enum REHASH_Hash_Type out_type,
		    const char *input,
		    size_t input_length,
		    const char *output,
		    size_t output_length,
		    REHASH_StoreContinuation cont,
		    void *cls);

/**
 * Search for hash->hash mappings.
 *
 * @param h handle to rehash service
 * @param options only the flag LOOPBACK_ONLY is supported
 * @param anonymity desired anonymity level
 * @param in_type type of hash to query with
 * @param out_type type of hash to search for
 * @param input hash to search with
 * @param input_length length of @a input_hash
 * @param cont continuation to call when something is found
 * @return handle to abort the request
 */
struct REHASH_QueryContext *
REHASH_query_start (struct REHASH_Handle *h,
		    enum GNUNET_FS_SearchOptions options,
		    uint32_t anonymity,
		    enum REHASH_Hash_Type in_type,
		    enum REHASH_Hash_Type out_type,
		    const char *input,
		    size_t input_length,
		    REHASH_QueryContinuation cont,
		    void *cls);

/**
 * Abort trying to store a hash->hash mapping.
 *
 * This deallocates @var{c}. No callbacks associated with @var{c}
 * will be called anymore.
 *
 * @param c context of action to abort
 */
void
REHASH_store_abort (struct REHASH_StoreContext *c);

/**
 * Abort a search.
 *
 * This deallocates @var{c}. No callbacks associated with @var{c}
 * will be called anymore.
 *
 * @param c context of action to abort
 */
void
REHASH_query_abort (struct REHASH_QueryContext *c);

#if 0
{
#endif
#ifdef __cplusplus
}
#endif

#endif