contrib/subversion/subversion/include/private/svn_repos_private.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_repos_private.h
  24  * @brief Subversion-internal repos APIs.
  25  */
  26
  27 #ifndef SVN_REPOS_PRIVATE_H
  28 #define SVN_REPOS_PRIVATE_H
  29
  30 #include <apr_pools.h>
  31
  32 #include "svn_types.h"
  33 #include "svn_repos.h"
  34 #include "svn_editor.h"
  35 #include "svn_config.h"
  36
  37 #include "private/svn_string_private.h"
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif /* __cplusplus */
  42
  43
  44 /** Validate that property @a name with @a value is valid (as an addition
  45  * or edit or deletion) in a Subversion repository.  Return an error if not.
  46  *
  47  * If @a value is NULL, return #SVN_NO_ERROR to indicate that any property
  48  * may be deleted, even an invalid one.  Otherwise, if the @a name is not
  49  * of kind #svn_prop_regular_kind (see #svn_prop_kind_t), return
  50  * #SVN_ERR_REPOS_BAD_ARGS.  Otherwise, for some "svn:" properties, also
  51  * perform some validations on the @a value (e.g., for such properties,
  52  * typically the @a value must be in UTF-8 with LF linefeeds), and return
  53  * #SVN_ERR_BAD_PROPERTY_VALUE if it is not valid.
  54  *
  55  * Validations may be added in future releases, for example, for
  56  * newly-added #SVN_PROP_PREFIX properties.  However, user-defined
  57  * (non-#SVN_PROP_PREFIX) properties will never have their @a value
  58  * validated in any way.
  59  *
  60  * Use @a pool for temporary allocations.
  61  *
  62  * @note This function is used to implement server-side validation.
  63  * Consequently, if you make this function stricter in what it accepts, you
  64  * (a) break svnsync'ing of existing repositories that contain now-invalid
  65  * properties, (b) do not preclude such invalid values from entering the
  66  * repository via tools that use the svn_fs_* API directly (possibly
  67  * including svnadmin and svnlook).  This has happened before and there
  68  * are known (documented, but unsupported) upgrade paths in some cases.
  69  *
  70  * @since New in 1.7.
  71  */
  72 svn_error_t *
  73 svn_repos__validate_prop(const char *name,
  74                          const svn_string_t *value,
  75                          apr_pool_t *pool);
  76
  77 /**
  78  * Given the error @a err from svn_repos_fs_commit_txn(), return an
  79  * string containing either or both of the svn_fs_commit_txn() error
  80  * and the SVN_ERR_REPOS_POST_COMMIT_HOOK_FAILED wrapped error from
  81  * the post-commit hook.  Any error tracing placeholders in the error
  82  * chain are skipped over.
  83  *
  84  * This function does not modify @a err.
  85  *
  86  * ### This method should not be necessary, but there are a few
  87  * ### places, e.g. mod_dav_svn, where only a single error message
  88  * ### string is returned to the caller and it is useful to have both
  89  * ### error messages included in the message.
  90  *
  91  * Use @a pool to do any allocations in.
  92  *
  93  * @since New in 1.7.
  94  */
  95 const char *
  96 svn_repos__post_commit_error_str(svn_error_t *err,
  97                                  apr_pool_t *pool);
  98
  99 /* A repos version of svn_fs_type */
 100 svn_error_t *
 101 svn_repos__fs_type(const char **fs_type,
 102                    const char *repos_path,
 103                    apr_pool_t *pool);
 104
 105
 106 /* Create a commit editor for REPOS, based on REVISION.  */
 107 svn_error_t *
 108 svn_repos__get_commit_ev2(svn_editor_t **editor,
 109                           svn_repos_t *repos,
 110                           svn_authz_t *authz,
 111                           const char *authz_repos_name,
 112                           const char *authz_user,
 113                           apr_hash_t *revprops,
 114                           svn_commit_callback2_t commit_cb,
 115                           void *commit_baton,
 116                           svn_cancel_func_t cancel_func,
 117                           void *cancel_baton,
 118                           apr_pool_t *result_pool,
 119                           apr_pool_t *scratch_pool);
 120
 121 svn_error_t *
 122 svn_repos__replay_ev2(svn_fs_root_t *root,
 123                       const char *base_dir,
 124                       svn_revnum_t low_water_mark,
 125                       svn_editor_t *editor,
 126                       svn_repos_authz_func_t authz_read_func,
 127                       void *authz_read_baton,
 128                       apr_pool_t *scratch_pool);
 129
 130 /* Given a PATH which might be a relative repo URL (^/), an absolute
 131  * local repo URL (file://), an absolute path outside of the repo
 132  * or a location in the Windows registry.
 133  *
 134  * Retrieve the configuration data that PATH points at and parse it into
 135  * CFG_P allocated in POOL.
 136  *
 137  * If PATH cannot be parsed as a config file then an error is returned.  The
 138  * contents of CFG_P is then undefined.  If MUST_EXIST is TRUE, a missing
 139  * authz file is also an error.  The CASE_SENSITIVE controls the lookup
 140  * behavior for section and option names alike.
 141  *
 142  * REPOS_ROOT points at the root of the repos you are
 143  * going to apply the authz against, can be NULL if you are sure that you
 144  * don't have a repos relative URL in PATH. */
 145 svn_error_t *
 146 svn_repos__retrieve_config(svn_config_t **cfg_p,
 147                            const char *path,
 148                            svn_boolean_t must_exist,
 149                            svn_boolean_t case_sensitive,
 150                            apr_pool_t *pool);
 151
 152 /**
 153  * @defgroup svn_config_pool Configuration object pool API
 154  * @{
 155  */
 156
 157 /* Opaque thread-safe factory and container for configuration objects.
 158  *
 159  * Instances handed out are read-only and may be given to multiple callers
 160  * from multiple threads.  Configuration objects no longer referenced by
 161  * any user may linger for a while before being cleaned up.
 162  */
 163 typedef struct svn_repos__config_pool_t svn_repos__config_pool_t;
 164
 165 /* Create a new configuration pool object with a lifetime determined by
 166  * POOL and return it in *CONFIG_POOL.
 167  *
 168  * The THREAD_SAFE flag indicates whether the pool actually needs to be
 169  * thread-safe and POOL must be also be thread-safe if this flag is set.
 170  */
 171 svn_error_t *
 172 svn_repos__config_pool_create(svn_repos__config_pool_t **config_pool,
 173                               svn_boolean_t thread_safe,
 174                               apr_pool_t *pool);
 175
 176 /* Set *CFG to a read-only reference to the current contents of the
 177  * configuration specified by PATH.  If the latter is a URL, we read the
 178  * data from a local repository.  CONFIG_POOL will store the configuration
 179  * and make further callers use the same instance if the content matches.
 180  * If KEY is not NULL, *KEY will be set to a unique ID - if available.
 181  *
 182  * If MUST_EXIST is TRUE, a missing config file is also an error, *CFG
 183  * is otherwise simply NULL.  The CASE_SENSITIVE controls the lookup
 184  * behavior for section and option names alike.
 185  *
 186  * PREFERRED_REPOS is only used if it is not NULL and PATH is a URL.
 187  * If it matches the URL, access the repository through this object
 188  * instead of creating a new repo instance.  Note that this might not
 189  * return the latest content.
 190  *
 191  * POOL determines the minimum lifetime of *CFG (may remain cached after
 192  * release) but must not exceed the lifetime of the pool provided to
 193  * #svn_repos__config_pool_create.
 194  */
 195 svn_error_t *
 196 svn_repos__config_pool_get(svn_config_t **cfg,
 197                            svn_membuf_t **key,
 198                            svn_repos__config_pool_t *config_pool,
 199                            const char *path,
 200                            svn_boolean_t must_exist,
 201                            svn_boolean_t case_sensitive,
 202                            svn_repos_t *preferred_repos,
 203                            apr_pool_t *pool);
 204
 205 /** @} */
 206
 207 /**
 208  * @defgroup svn_authz_pool Authz object pool API
 209  * @{
 210  */
 211
 212 /* Opaque thread-safe factory and container for authorization objects.
 213  *
 214  * Instances handed out are read-only and may be given to multiple callers
 215  * from multiple threads.  Authorization objects no longer referenced by
 216  * any user may linger for a while before being cleaned up.
 217  */
 218 typedef struct svn_repos__authz_pool_t svn_repos__authz_pool_t;
 219
 220 /* Create a new authorization pool object with a lifetime determined by
 221  * POOL and return it in *AUTHZ_POOL.  CONFIG_POOL will be the common
 222  * source for the configuration data underlying the authz objects and must
 223  * remain valid at least until POOL cleanup.
 224  *
 225  * The THREAD_SAFE flag indicates whether the pool actually needs to be
 226  * thread-safe and POOL must be also be thread-safe if this flag is set.
 227  */
 228 svn_error_t *
 229 svn_repos__authz_pool_create(svn_repos__authz_pool_t **authz_pool,
 230                              svn_repos__config_pool_t *config_pool,
 231                              svn_boolean_t thread_safe,
 232                              apr_pool_t *pool);
 233
 234 /* Set *AUTHZ_P to a read-only reference to the current contents of the
 235  * authorization specified by PATH and GROUPS_PATH.  If these are URLs,
 236  * we read the data from a local repository (see #svn_repos_authz_read2).
 237  * AUTHZ_POOL will store the authz data and make further callers use the
 238  * same instance if the content matches.
 239  *
 240  * If MUST_EXIST is TRUE, a missing config file is also an error, *AUTHZ_P
 241  * is otherwise simply NULL.
 242  *
 243  * PREFERRED_REPOS is only used if it is not NULL and PATH is a URL.
 244  * If it matches the URL, access the repository through this object
 245  * instead of creating a new repo instance.  Note that this might not
 246  * return the latest content.
 247  *
 248  * POOL determines the minimum lifetime of *AUTHZ_P (may remain cached
 249  * after release) but must not exceed the lifetime of the pool provided to
 250  * svn_repos__authz_pool_create.
 251  */
 252 svn_error_t *
 253 svn_repos__authz_pool_get(svn_authz_t **authz_p,
 254                           svn_repos__authz_pool_t *authz_pool,
 255                           const char *path,
 256                           const char *groups_path,
 257                           svn_boolean_t must_exist,
 258                           svn_repos_t *preferred_repos,
 259                           apr_pool_t *pool);
 260
 261 /** @} */
 262
 263 /* Adjust mergeinfo paths and revisions in ways that are useful when loading
 264  * a dump stream.
 265  *
 266  * Set *NEW_VALUE_P to an adjusted version of the mergeinfo property value
 267  * supplied in OLD_VALUE, with the following adjustments.
 268  *
 269  *   - Normalize line endings: if all CRLF, change to LF; but error if
 270  *     mixed. If this normalization is performed, send a notification type
 271  *     svn_repos_notify_load_normalized_mergeinfo to NOTIFY_FUNC/NOTIFY_BATON.
 272  *
 273  *   - Prefix all the merge source paths with PARENT_DIR, if not null.
 274  *
 275  *   - Adjust any mergeinfo revisions not older than OLDEST_DUMPSTREAM_REV
 276  *     by using REV_MAP which maps (svn_revnum_t) old rev to (svn_revnum_t)
 277  *     new rev.
 278  *
 279  *   - Adjust any mergeinfo revisions older than OLDEST_DUMPSTREAM_REV by
 280  *     (-OLDER_REVS_OFFSET), dropping any revisions that become <= 0.
 281  *
 282  * Allocate *NEW_VALUE_P in RESULT_POOL.
 283  */
 284 svn_error_t *
 285 svn_repos__adjust_mergeinfo_property(svn_string_t **new_value_p,
 286                                      const svn_string_t *old_value,
 287                                      const char *parent_dir,
 288                                      apr_hash_t *rev_map,
 289                                      svn_revnum_t oldest_dumpstream_rev,
 290                                      apr_int32_t older_revs_offset,
 291                                      svn_repos_notify_func_t notify_func,
 292                                      void *notify_baton,
 293                                      apr_pool_t *result_pool,
 294                                      apr_pool_t *scratch_pool);
 295
 296 /* A (nearly) opaque representation of an ordered list of header lines.
 297  */
 298 typedef struct apr_array_header_t svn_repos__dumpfile_headers_t;
 299
 300 /* Create an empty set of headers.
 301  */
 302 svn_repos__dumpfile_headers_t *
 303 svn_repos__dumpfile_headers_create(apr_pool_t *pool);
 304
 305 /* Push the header (KEY, VAL) onto HEADERS.
 306  *
 307  * Duplicate the key and value into HEADERS's pool.
 308  */
 309 void
 310 svn_repos__dumpfile_header_push(svn_repos__dumpfile_headers_t *headers,
 311                                 const char *key,
 312                                 const char *val);
 313
 314 /* Push the header (KEY, val = VAL_FMT ...) onto HEADERS.
 315  *
 316  * Duplicate the key and value into HEADERS's pool.
 317  */
 318 void
 319 svn_repos__dumpfile_header_pushf(svn_repos__dumpfile_headers_t *headers,
 320                                  const char *key,
 321                                  const char *val_fmt,
 322                                  ...)
 323         __attribute__((format(printf, 3, 4)));
 324
 325 /* Write to STREAM the headers in HEADERS followed by a blank line.
 326  */
 327 svn_error_t *
 328 svn_repos__dump_headers(svn_stream_t *stream,
 329                         svn_repos__dumpfile_headers_t *headers,
 330                         apr_pool_t *scratch_pool);
 331
 332 /* Write a revision record to DUMP_STREAM for revision REVISION with revision
 333  * properies REVPROPS, creating appropriate headers.
 334  *
 335  * Include all of the headers in EXTRA_HEADERS (if non-null), ignoring
 336  * the revision number header and the three content length headers (which
 337  * will be recreated as needed). EXTRA_HEADERS maps (char *) key to
 338  * (char *) value.
 339  *
 340  * REVPROPS maps (char *) key to (svn_string_t *) value.
 341  *
 342  * Iff PROPS_SECTION_ALWAYS is true, include a prop content section (and
 343  * corresponding header) even when REVPROPS is empty. This option exists
 344  * to support a historical difference between svndumpfilter and svnadmin
 345  * dump.
 346  *
 347  * Finally write another blank line.
 348  */
 349 svn_error_t *
 350 svn_repos__dump_revision_record(svn_stream_t *dump_stream,
 351                                 svn_revnum_t revision,
 352                                 apr_hash_t *extra_headers,
 353                                 apr_hash_t *revprops,
 354                                 svn_boolean_t props_section_always,
 355                                 apr_pool_t *scratch_pool);
 356
 357 /* Output node headers and props.
 358  *
 359  * Output HEADERS, content length headers, blank line, and
 360  * then PROPS_STR (if non-null) to DUMP_STREAM.
 361  *
 362  * HEADERS is an array of headers as struct {const char *key, *val;}.
 363  * Write them all in the given order.
 364  *
 365  * PROPS_STR is the property content block, including a terminating
 366  * 'PROPS_END\n' line. Iff PROPS_STR is non-null, write a
 367  * Prop-content-length header and the prop content block.
 368  *
 369  * Iff HAS_TEXT is true, write a Text-content length, using the value
 370  * TEXT_CONTENT_LENGTH.
 371  *
 372  * Write a Content-length header, its value being the sum of the
 373  * Prop- and Text- content length headers, if props and/or text are present
 374  * or if CONTENT_LENGTH_ALWAYS is true.
 375  */
 376 svn_error_t *
 377 svn_repos__dump_node_record(svn_stream_t *dump_stream,
 378                             svn_repos__dumpfile_headers_t *headers,
 379                             svn_stringbuf_t *props_str,
 380                             svn_boolean_t has_text,
 381                             svn_filesize_t text_content_length,
 382                             svn_boolean_t content_length_always,
 383                             apr_pool_t *scratch_pool);
 384
 385 #ifdef __cplusplus
 386 }
 387 #endif /* __cplusplus */
 388
 389 #endif /* SVN_REPOS_PRIVATE_H */