/*-------------------------------------------------------------------------

 *

 * 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;

}