src/bin/pg_basebackup/bbstreamer.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * bbstreamer.h
   4  *
   5  * Each tar archive returned by the server is passed to one or more
   6  * bbstreamer objects for further processing. The bbstreamer may do
   7  * something simple, like write the archive to a file, perhaps after
   8  * compressing it, but it can also do more complicated things, like
   9  * annotating the byte stream to indicate which parts of the data
  10  * correspond to tar headers or trailing padding, vs. which parts are
  11  * payload data. A subsequent bbstreamer may use this information to
  12  * make further decisions about how to process the data; for example,
  13  * it might choose to modify the archive contents.
  14  *
  15  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
  16  *
  17  * IDENTIFICATION
  18  *                src/bin/pg_basebackup/bbstreamer.h
  19  *-------------------------------------------------------------------------
  20  */
  21
  22 #ifndef BBSTREAMER_H
  23 #define BBSTREAMER_H
  24
  25 #include "lib/stringinfo.h"
  26 #include "pqexpbuffer.h"
  27
  28 struct bbstreamer;
  29 struct bbstreamer_ops;
  30 typedef struct bbstreamer bbstreamer;
  31 typedef struct bbstreamer_ops bbstreamer_ops;
  32
  33 /*
  34  * Each chunk of archive data passed to a bbstreamer is classified into one
  35  * of these categories. When data is first received from the remote server,
  36  * each chunk will be categorized as BBSTREAMER_UNKNOWN, and the chunks will
  37  * be of whatever size the remote server chose to send.
  38  *
  39  * If the archive is parsed (e.g. see bbstreamer_tar_parser_new()), then all
  40  * chunks should be labelled as one of the other types listed here. In
  41  * addition, there should be exactly one BBSTREAMER_MEMBER_HEADER chunk and
  42  * exactly one BBSTREAMER_MEMBER_TRAILER chunk per archive member, even if
  43  * that means a zero-length call. There can be any number of
  44  * BBSTREAMER_MEMBER_CONTENTS chunks in between those calls. There
  45  * should exactly BBSTREAMER_ARCHIVE_TRAILER chunk, and it should follow the
  46  * last BBSTREAMER_MEMBER_TRAILER chunk.
  47  *
  48  * In theory, we could need other classifications here, such as a way of
  49  * indicating an archive header, but the "tar" format doesn't need anything
  50  * else, so for the time being there's no point.
  51  */
  52 typedef enum
  53 {
  54         BBSTREAMER_UNKNOWN,
  55         BBSTREAMER_MEMBER_HEADER,
  56         BBSTREAMER_MEMBER_CONTENTS,
  57         BBSTREAMER_MEMBER_TRAILER,
  58         BBSTREAMER_ARCHIVE_TRAILER
  59 } bbstreamer_archive_context;
  60
  61 /*
  62  * Each chunk of data that is classified as BBSTREAMER_MEMBER_HEADER,
  63  * BBSTREAMER_MEMBER_CONTENTS, or BBSTREAMER_MEMBER_TRAILER should also
  64  * pass a pointer to an instance of this struct. The details are expected
  65  * to be present in the archive header and used to fill the struct, after
  66  * which all subsequent calls for the same archive member are expected to
  67  * pass the same details.
  68  */
  69 typedef struct
  70 {
  71         char            pathname[MAXPGPATH];
  72         pgoff_t         size;
  73         mode_t          mode;
  74         uid_t           uid;
  75         gid_t           gid;
  76         bool            is_directory;
  77         bool            is_link;
  78         char            linktarget[MAXPGPATH];
  79 } bbstreamer_member;
  80
  81 /*
  82  * Generally, each type of bbstreamer will define its own struct, but the
  83  * first element should be 'bbstreamer base'. A bbstreamer that does not
  84  * require any additional private data could use this structure directly.
  85  *
  86  * bbs_ops is a pointer to the bbstreamer_ops object which contains the
  87  * function pointers appropriate to this type of bbstreamer.
  88  *
  89  * bbs_next is a pointer to the successor bbstreamer, for those types of
  90  * bbstreamer which forward data to a successor. It need not be used and
  91  * should be set to NULL when not relevant.
  92  *
  93  * bbs_buffer is a buffer for accumulating data for temporary storage. Each
  94  * type of bbstreamer makes its own decisions about whether and how to use
  95  * this buffer.
  96  */
  97 struct bbstreamer
  98 {
  99         const bbstreamer_ops *bbs_ops;
 100         bbstreamer *bbs_next;
 101         StringInfoData bbs_buffer;
 102 };
 103
 104 /*
 105  * There are three callbacks for a bbstreamer. The 'content' callback is
 106  * called repeatedly, as described in the bbstreamer_archive_context comments.
 107  * Then, the 'finalize' callback is called once at the end, to give the
 108  * bbstreamer a chance to perform cleanup such as closing files. Finally,
 109  * because this code is running in a frontend environment where, as of this
 110  * writing, there are no memory contexts, the 'free' callback is called to
 111  * release memory. These callbacks should always be invoked using the static
 112  * inline functions defined below.
 113  */
 114 struct bbstreamer_ops
 115 {
 116         void            (*content) (bbstreamer *streamer, bbstreamer_member *member,
 117                                                         const char *data, int len,
 118                                                         bbstreamer_archive_context context);
 119         void            (*finalize) (bbstreamer *streamer);
 120         void            (*free) (bbstreamer *streamer);
 121 };
 122
 123 /* Send some content to a bbstreamer. */
 124 static inline void
 125 bbstreamer_content(bbstreamer *streamer, bbstreamer_member *member,
 126                                    const char *data, int len,
 127                                    bbstreamer_archive_context context)
 128 {
 129         Assert(streamer != NULL);
 130         streamer->bbs_ops->content(streamer, member, data, len, context);
 131 }
 132
 133 /* Finalize a bbstreamer. */
 134 static inline void
 135 bbstreamer_finalize(bbstreamer *streamer)
 136 {
 137         Assert(streamer != NULL);
 138         streamer->bbs_ops->finalize(streamer);
 139 }
 140
 141 /* Free a bbstreamer. */
 142 static inline void
 143 bbstreamer_free(bbstreamer *streamer)
 144 {
 145         Assert(streamer != NULL);
 146         streamer->bbs_ops->free(streamer);
 147 }
 148
 149 /*
 150  * This is a convenience method for use when implementing a bbstreamer; it is
 151  * not for use by outside callers. It adds the amount of data specified by
 152  * 'nbytes' to the bbstreamer's buffer and adjusts '*len' and '*data'
 153  * accordingly.
 154  */
 155 static inline void
 156 bbstreamer_buffer_bytes(bbstreamer *streamer, const char **data, int *len,
 157                                                 int nbytes)
 158 {
 159         Assert(nbytes <= *len);
 160
 161         appendBinaryStringInfo(&streamer->bbs_buffer, *data, nbytes);
 162         *len -= nbytes;
 163         *data += nbytes;
 164 }
 165
 166 /*
 167  * This is a convenence method for use when implementing a bbstreamer; it is
 168  * not for use by outsider callers. It attempts to add enough data to the
 169  * bbstreamer's buffer to reach a length of target_bytes and adjusts '*len'
 170  * and '*data' accordingly. It returns true if the target length has been
 171  * reached and false otherwise.
 172  */
 173 static inline bool
 174 bbstreamer_buffer_until(bbstreamer *streamer, const char **data, int *len,
 175                                                 int target_bytes)
 176 {
 177         int                     buflen = streamer->bbs_buffer.len;
 178
 179         if (buflen >= target_bytes)
 180         {
 181                 /* Target length already reached; nothing to do. */
 182                 return true;
 183         }
 184
 185         if (buflen + *len < target_bytes)
 186         {
 187                 /* Not enough data to reach target length; buffer all of it. */
 188                 bbstreamer_buffer_bytes(streamer, data, len, *len);
 189                 return false;
 190         }
 191
 192         /* Buffer just enough to reach the target length. */
 193         bbstreamer_buffer_bytes(streamer, data, len, target_bytes - buflen);
 194         return true;
 195 }
 196
 197 /*
 198  * Functions for creating bbstreamer objects of various types. See the header
 199  * comments for each of these functions for details.
 200  */
 201 extern bbstreamer *bbstreamer_plain_writer_new(char *pathname, FILE *file);
 202 extern bbstreamer *bbstreamer_gzip_writer_new(char *pathname, FILE *file,
 203                                                                                           int compresslevel);
 204 extern bbstreamer *bbstreamer_extractor_new(const char *basepath,
 205                                                                                         const char *(*link_map) (const char *),
 206                                                                                         void (*report_output_file) (const char *));
 207
 208 extern bbstreamer *bbstreamer_tar_parser_new(bbstreamer *next);
 209 extern bbstreamer *bbstreamer_tar_terminator_new(bbstreamer *next);
 210 extern bbstreamer *bbstreamer_tar_archiver_new(bbstreamer *next);
 211
 212 extern bbstreamer *bbstreamer_recovery_injector_new(bbstreamer *next,
 213                                                                                                         bool is_recovery_guc_supported,
 214                                                                                                         PQExpBuffer recoveryconfcontents);
 215 extern void bbstreamer_inject_file(bbstreamer *streamer, char *pathname,
 216                                                                    char *data, int len);
 217
 218 #endif