/*-------------------------------------------------------------------------
 *
 * basebackup_target.c
 *   Base backups can be "targeted", which means that they can be sent
 *   somewhere other than to the client which requested the backup.
 *   Furthermore, new targets can be defined by extensions. This file
 *   contains code to support that functionality.
 *
 * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
 *
 * IDENTIFICATION
 *   src/backend/backup/basebackup_target.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"

#include "backup/basebackup_target.h"
#include "utils/memutils.h"

typedef struct BaseBackupTargetType
{
 char    *name;
 void    *(*check_detail) (char *, char *);
 bbsink    *(*get_sink) (bbsink *, void *);
} BaseBackupTargetType;

struct BaseBackupTargetHandle
{
 BaseBackupTargetType *type;
 void    *detail_arg;
};

static void initialize_target_list(void);
static bbsink *blackhole_get_sink(bbsink *next_sink, void *detail_arg);
static bbsink *server_get_sink(bbsink *next_sink, void *detail_arg);
static void *reject_target_detail(char *target, char *target_detail);
static void *server_check_detail(char *target, char *target_detail);

static BaseBackupTargetType builtin_backup_targets[] =
{
 {
  "blackhole", reject_target_detail, blackhole_get_sink
 },
 {
  "server", server_check_detail, server_get_sink
 },
 {
  NULL
 }
};

static List *BaseBackupTargetTypeList = NIL;

/*
 * Add a new base backup target type.
 *
 * This is intended for use by server extensions.
 */
void
BaseBackupAddTarget(char *name,
     void *(*check_detail) (char *, char *),
     bbsink *(*get_sink) (bbsink *, void *))
{
 BaseBackupTargetType *newtype;
 MemoryContext oldcontext;
 ListCell   *lc;

 /* If the target list is not yet initialized, do that first. */
 if (BaseBackupTargetTypeList == NIL)
  initialize_target_list();

 /* Search the target type list for an existing entry with this name. */
 foreach(lc, BaseBackupTargetTypeList)
 {
  BaseBackupTargetType *ttype = lfirst(lc);

  if (strcmp(ttype->name, name) == 0)
  {
   /*
    * We found one, so update it.
    *
    * It is probably not a great idea to call BaseBackupAddTarget for
    * the same name multiple times, but if it happens, this seems
    * like the sanest behavior.
 */
   ttype->check_detail = check_detail;
   ttype->get_sink = get_sink;
   return;
  }
 }

 /*
  * We use TopMemoryContext for allocations here to make sure that the data
  * we need doesn't vanish under us; that's also why we copy the target
  * name into a newly-allocated chunk of memory.
 */
 oldcontext = MemoryContextSwitchTo(TopMemoryContext);
 newtype = palloc(sizeof(BaseBackupTargetType));
 newtype->name = pstrdup(name);
 newtype->check_detail = check_detail;
 newtype->get_sink = get_sink;
 BaseBackupTargetTypeList = lappend(BaseBackupTargetTypeList, newtype);
 MemoryContextSwitchTo(oldcontext);
}

/*
 * Look up a base backup target and validate the target_detail.
 *
 * Extensions that define new backup targets will probably define a new
 * type of bbsink to match. Validation of the target_detail can be performed
 * either in the check_detail routine called here, or in the bbsink
 * constructor, which will be called from BaseBackupGetSink. It's mostly
 * a matter of taste, but the check_detail function runs somewhat earlier.
 */
BaseBackupTargetHandle *
BaseBackupGetTargetHandle(char *target, char *target_detail)
{
 ListCell   *lc;

 /* If the target list is not yet initialized, do that first. */
 if (BaseBackupTargetTypeList == NIL)
  initialize_target_list();

 /* Search the target type list for a match. */
 foreach(lc, BaseBackupTargetTypeList)
 {
  BaseBackupTargetType *ttype = lfirst(lc);

  if (strcmp(ttype->name, target) == 0)
  {
   BaseBackupTargetHandle *handle;

   /* Found the target. */
   handle = palloc(sizeof(BaseBackupTargetHandle));
   handle->type = ttype;
   handle->detail_arg = ttype->check_detail(target, target_detail);

   return handle;
  }
 }

 /* Did not find the target. */
 ereport(ERROR,
   (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
    errmsg("unrecognized target: \"%s\"", target)));

 /* keep compiler quiet */
 return NULL;
}

/*
 * Construct a bbsink that will implement the backup target.
 *
 * The get_sink function does all the real work, so all we have to do here
 * is call it with the correct arguments. Whatever the check_detail function
 * returned is here passed through to the get_sink function. This lets those
 * two functions communicate with each other, if they wish. If not, the
 * check_detail function can simply return the target_detail and let the
 * get_sink function take it from there.
 */
bbsink *
BaseBackupGetSink(BaseBackupTargetHandle *handle, bbsink *next_sink)
{
 return handle->type->get_sink(next_sink, handle->detail_arg);
}

/*
 * Load predefined target types into BaseBackupTargetTypeList.
 */
static void
initialize_target_list(void)
{
 BaseBackupTargetType *ttype = builtin_backup_targets;
 MemoryContext oldcontext;

 oldcontext = MemoryContextSwitchTo(TopMemoryContext);
 while (ttype->name != NULL)
 {
  BaseBackupTargetTypeList = lappend(BaseBackupTargetTypeList, ttype);
  ++ttype;
 }
 MemoryContextSwitchTo(oldcontext);
}

/*
 * Normally, a get_sink function should construct and return a new bbsink that
 * implements the backup target, but the 'blackhole' target just throws the
 * data away. We could implement that by adding a bbsink that does nothing
 * but forward, but it's even cheaper to implement that by not adding a bbsink
 * at all.
 */
static bbsink *
blackhole_get_sink(bbsink *next_sink, void *detail_arg)
{
 return next_sink;
}

/*
 * Create a bbsink implementing a server-side backup.
 */
static bbsink *
server_get_sink(bbsink *next_sink, void *detail_arg)
{
 return bbsink_server_new(next_sink, detail_arg);
}

/*
 * Implement target-detail checking for a target that does not accept a
 * detail.
 */
static void *
reject_target_detail(char *target, char *target_detail)
{
 if (target_detail != NULL)
  ereport(ERROR,
    (errcode(ERRCODE_SYNTAX_ERROR),
     errmsg("target \"%s\" does not accept a target detail",
      target)));

 return NULL;
}

/*
 * Implement target-detail checking for a server-side backup.
 *
 * target_detail should be the name of the directory to which the backup
 * should be written, but we don't check that here. Rather, that check,
 * as well as the necessary permissions checking, happens in bbsink_server_new.
 */
static void *
server_check_detail(char *target, char *target_detail)
{
 if (target_detail == NULL)
  ereport(ERROR,
    (errcode(ERRCODE_SYNTAX_ERROR),
     errmsg("target \"%s\" requires a target detail",
      target)));

 return target_detail;
}