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
12 * http://www.apache.org/licenses/LICENSE-2.0
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
20 * ====================================================================
24 * @brief libsvn_ra_svn functions used by the server
31 #include <apr_pools.h>
33 #include <apr_tables.h>
34 #include <apr_file_io.h> /* for apr_file_t */
35 #include <apr_network_io.h> /* for apr_socket_t */
37 #include "svn_types.h"
38 #include "svn_string.h"
39 #include "svn_config.h"
40 #include "svn_delta.h"
44 #endif /* __cplusplus */
46 /** The well-known svn port number. */
47 #define SVN_RA_SVN_PORT 3690
49 /** Currently-defined capabilities. */
50 #define SVN_RA_SVN_CAP_EDIT_PIPELINE "edit-pipeline"
51 #define SVN_RA_SVN_CAP_SVNDIFF1 "svndiff1"
52 #define SVN_RA_SVN_CAP_SVNDIFF2_ACCEPTED "accepts-svndiff2"
53 #define SVN_RA_SVN_CAP_ABSENT_ENTRIES "absent-entries"
54 /* maps to SVN_RA_CAPABILITY_COMMIT_REVPROPS: */
55 #define SVN_RA_SVN_CAP_COMMIT_REVPROPS "commit-revprops"
56 /* maps to SVN_RA_CAPABILITY_MERGEINFO: */
57 #define SVN_RA_SVN_CAP_MERGEINFO "mergeinfo"
58 /* maps to SVN_RA_CAPABILITY_DEPTH: */
59 #define SVN_RA_SVN_CAP_DEPTH "depth"
60 /* maps to SVN_RA_CAPABILITY_LOG_REVPROPS */
61 #define SVN_RA_SVN_CAP_LOG_REVPROPS "log-revprops"
62 /* maps to SVN_RA_CAPABILITY_PARTIAL_REPLAY */
63 #define SVN_RA_SVN_CAP_PARTIAL_REPLAY "partial-replay"
64 /* maps to SVN_RA_CAPABILITY_ATOMIC_REVPROPS */
65 #define SVN_RA_SVN_CAP_ATOMIC_REVPROPS "atomic-revprops"
66 /* maps to SVN_RA_CAPABILITY_INHERITED_PROPERTIES: */
67 #define SVN_RA_SVN_CAP_INHERITED_PROPS "inherited-props"
68 /* maps to SVN_RA_CAPABILITY_EPHEMERAL_TXNPROPS */
69 #define SVN_RA_SVN_CAP_EPHEMERAL_TXNPROPS "ephemeral-txnprops"
70 /* maps to SVN_RA_CAPABILITY_GET_FILE_REVS_REVERSE */
71 #define SVN_RA_SVN_CAP_GET_FILE_REVS_REVERSE "file-revs-reverse"
72 /* maps to SVN_RA_CAPABILITY_LIST */
73 #define SVN_RA_SVN_CAP_LIST "list"
76 /** ra_svn passes @c svn_dirent_t fields over the wire as a list of
77 * words, these are the values used to represent each field.
79 * @defgroup ra_svn_dirent_fields Definitions of ra_svn dirent fields
83 /** The ra_svn way of saying @c SVN_DIRENT_KIND. */
84 #define SVN_RA_SVN_DIRENT_KIND "kind"
86 /** The ra_svn way of saying @c SVN_DIRENT_SIZE. */
87 #define SVN_RA_SVN_DIRENT_SIZE "size"
89 /** The ra_svn way of saying @c SVN_DIRENT_HAS_PROPS. */
90 #define SVN_RA_SVN_DIRENT_HAS_PROPS "has-props"
92 /** The ra_svn way of saying @c SVN_DIRENT_CREATED_REV. */
93 #define SVN_RA_SVN_DIRENT_CREATED_REV "created-rev"
95 /** The ra_svn way of saying @c SVN_DIRENT_TIME. */
96 #define SVN_RA_SVN_DIRENT_TIME "time"
98 /** The ra_svn way of saying @c SVN_DIRENT_LAST_AUTHOR. */
99 #define SVN_RA_SVN_DIRENT_LAST_AUTHOR "last-author"
103 /** A value used to indicate an optional number element in a tuple that was
106 #define SVN_RA_SVN_UNSPECIFIED_NUMBER ~((apr_uint64_t) 0)
108 /** A specialized form of @c SVN_ERR to deal with errors which occur in an
109 * svn_ra_svn_command_handler().
111 * An error returned with this macro will be passed back to the other side
112 * of the connection. Use this macro when performing the requested operation;
113 * use the regular @c SVN_ERR when performing I/O with the client.
115 #define SVN_CMD_ERR(expr) \
117 svn_error_t *svn_err__temp = (expr); \
119 return svn_error_create(SVN_ERR_RA_SVN_CMD_ERR, \
120 svn_err__temp, NULL); \
123 /** an ra_svn connection. */
124 typedef struct svn_ra_svn_conn_st svn_ra_svn_conn_t;
126 /** Command handler, used by svn_ra_svn_handle_commands(). */
127 typedef svn_error_t *(*svn_ra_svn_command_handler)(svn_ra_svn_conn_t *conn,
129 apr_array_header_t *params,
132 /** Command table, used by svn_ra_svn_handle_commands().
134 typedef struct svn_ra_svn_cmd_entry_t
136 /** Name of the command */
139 /** Handler for the command */
140 svn_ra_svn_command_handler handler;
142 /** Termination flag. If set, command-handling will cease after
143 * command is processed. */
144 svn_boolean_t terminate;
145 } svn_ra_svn_cmd_entry_t;
147 /** Data types defined by the svn:// protocol.
149 * @since The typedef name is new in 1.10; the enumerators are not. */
156 } svn_ra_svn_item_kind_t;
158 /** Memory representation of an on-the-wire data item. */
159 typedef struct svn_ra_svn_item_t
161 /** Variant indicator. */
162 svn_ra_svn_item_kind_t kind;
167 svn_string_t *string;
170 /** Contains @c svn_ra_svn_item_t's. */
171 apr_array_header_t *list;
175 typedef svn_error_t *(*svn_ra_svn_edit_callback)(void *baton);
177 /** Initialize a connection structure for the given socket or
178 * input/output streams.
180 * Either @a sock or @a in_stream/@a out_stream must be set, not both.
181 * @a compression_level specifies the desired network data compression
182 * level from 0 (no compression) to 9 (best but slowest). The effect
183 * of the parameter depends on the compression algorithm; for example,
184 * it is used verbatim by zlib/deflate but ignored by LZ4.
186 * If @a zero_copy_limit is not 0, cached file contents smaller than the
187 * given limit may be sent directly to the network socket. Otherwise,
188 * it will be copied into a temporary buffer before being forwarded to
189 * the network stack. Since the zero-copy code path has to enforce strict
190 * time-outs, the receiver must be able to process @a zero_copy_limit
191 * bytes within one second. Even temporary failure to do so may cause
192 * the server to cancel the respective operation with a time-out error.
194 * To reduce the overhead of checking for cancellation requests from the
195 * data receiver, set @a error_check_interval to some non-zero value.
196 * It defines the number of bytes that must have been sent since the last
197 * check before the next check will be made.
199 * If @a max_in is not 0, error out and close the connection whenever more
200 * than @a max_in bytes are received for a command (e.g. a client request).
201 * If @a max_out is not 0, error out and close the connection whenever more
202 * than @a max_out bytes have been send as response to some command.
204 * @note The limits enforced may vary slightly by +/- the I/O buffer size.
206 * @note If @a out_stream is an wrapped apr_file_t* the backing file will be
207 * used for some operations.
209 * Allocate the result in @a pool.
213 svn_ra_svn_conn_t *svn_ra_svn_create_conn5(apr_socket_t *sock,
214 svn_stream_t *in_stream,
215 svn_stream_t *out_stream,
216 int compression_level,
217 apr_size_t zero_copy_limit,
218 apr_size_t error_check_interval,
220 apr_uint64_t max_out,
221 apr_pool_t *result_pool);
224 /** Similar to svn_ra_svn_create_conn5() but with @a max_in and @a max_out
228 * @deprecated Provided for backward compatibility with the 1.9 API.
231 svn_ra_svn_conn_t *svn_ra_svn_create_conn4(apr_socket_t *sock,
232 svn_stream_t *in_stream,
233 svn_stream_t *out_stream,
234 int compression_level,
235 apr_size_t zero_copy_limit,
236 apr_size_t error_check_interval,
237 apr_pool_t *result_pool);
240 /** Similar to svn_ra_svn_create_conn4() but only supports apr_file_t handles
241 * instead of the more generic streams.
244 * @deprecated Provided for backward compatibility with the 1.8 API.
247 svn_ra_svn_conn_t *svn_ra_svn_create_conn3(apr_socket_t *sock,
249 apr_file_t *out_file,
250 int compression_level,
251 apr_size_t zero_copy_limit,
252 apr_size_t error_check_interval,
255 /** Similar to svn_ra_svn_create_conn3() but disables the zero copy code
256 * path and sets the error checking interval to 0.
260 * @deprecated Provided for backward compatibility with the 1.7 API.
264 svn_ra_svn_create_conn2(apr_socket_t *sock,
266 apr_file_t *out_file,
267 int compression_level,
270 /** Similar to svn_ra_svn_create_conn2() but uses the default
271 * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT) for network
274 * @deprecated Provided for backward compatibility with the 1.6 API.
278 svn_ra_svn_create_conn(apr_socket_t *sock,
280 apr_file_t *out_file,
283 /** Add the capabilities in @a list to @a conn's capabilities.
284 * @a list contains svn_ra_svn_item_t entries (which should be of type
285 * SVN_RA_SVN_WORD; a malformed data error will result if any are not).
287 * This is idempotent: if a given capability was already set for
288 * @a conn, it remains set.
291 svn_ra_svn_set_capabilities(svn_ra_svn_conn_t *conn,
292 const apr_array_header_t *list);
294 /** Return @c TRUE if @a conn has the capability @a capability, or
295 * @c FALSE if it does not. */
297 svn_ra_svn_has_capability(svn_ra_svn_conn_t *conn,
298 const char *capability);
300 /** Return the data compression level to use for network transmissions.
305 svn_ra_svn_compression_level(svn_ra_svn_conn_t *conn);
307 /** Return the zero-copy data block limit to use for network
310 * @see http://en.wikipedia.org/wiki/Zero-copy
315 svn_ra_svn_zero_copy_limit(svn_ra_svn_conn_t *conn);
317 /** Returns the remote address of the connection as a string, if known,
318 * or NULL if inapplicable. */
320 svn_ra_svn_conn_remote_host(svn_ra_svn_conn_t *conn);
322 /** Set @a *editor and @a *edit_baton to an editor which will pass editing
323 * operations over the network, using @a conn and @a pool.
325 * Upon successful completion of the edit, the editor will invoke @a callback
326 * with @a callback_baton as an argument.
328 * @note The @c copyfrom_path parameter passed to the @c add_file and
329 * @c add_directory methods of the returned editor may be either a URL or a
330 * relative path, and is transferred verbatim to the receiving end of the
331 * connection. See svn_ra_svn_drive_editor2() for information on the
332 * receiving end of the connection.
335 svn_ra_svn_get_editor(const svn_delta_editor_t **editor,
337 svn_ra_svn_conn_t *conn,
339 svn_ra_svn_edit_callback callback,
340 void *callback_baton);
342 /** Receive edit commands over the network and use them to drive @a editor
343 * with @a edit_baton. On return, @a *aborted will be set if the edit was
344 * aborted. The drive can be terminated with a finish-replay command only
345 * if @a for_replay is TRUE.
349 * @note The @c copyfrom_path parameter passed to the @c add_file and
350 * @c add_directory methods of the receiving editor will be canonicalized
351 * either as a URL or as a relative path (starting with a slash) according
352 * to which kind was sent by the driving end of the connection. See
353 * svn_ra_svn_get_editor() for information on the driving end of the
357 svn_ra_svn_drive_editor2(svn_ra_svn_conn_t *conn,
359 const svn_delta_editor_t *editor,
361 svn_boolean_t *aborted,
362 svn_boolean_t for_replay);
364 /** Like svn_ra_svn_drive_editor2, but with @a for_replay always FALSE.
366 * @deprecated Provided for backward compatibility with the 1.3 API.
370 svn_ra_svn_drive_editor(svn_ra_svn_conn_t *conn,
372 const svn_delta_editor_t *editor,
374 svn_boolean_t *aborted);
376 /** This function is only intended for use by svnserve.
378 * Perform CRAM-MD5 password authentication. On success, return
379 * SVN_NO_ERROR with *user set to the username and *success set to
380 * TRUE. On an error which can be reported to the client, report the
381 * error and return SVN_NO_ERROR with *success set to FALSE. On
382 * communications failure, return an error.
385 svn_ra_svn_cram_server(svn_ra_svn_conn_t *conn,
389 svn_boolean_t *success);
392 * Get libsvn_ra_svn version information.
395 const svn_version_t *
396 svn_ra_svn_version(void);
399 * @defgroup ra_svn_deprecated ra_svn low-level functions
403 /** Write a number over the net.
405 * Writes will be buffered until the next read or flush.
407 * @deprecated Provided for backward compatibility with the 1.7 API.
408 * RA_SVN low-level functions are no longer considered public.
412 svn_ra_svn_write_number(svn_ra_svn_conn_t *conn,
414 apr_uint64_t number);
416 /** Write a string over the net.
418 * Writes will be buffered until the next read or flush.
420 * @deprecated Provided for backward compatibility with the 1.7 API.
421 * RA_SVN low-level functions are no longer considered public.
425 svn_ra_svn_write_string(svn_ra_svn_conn_t *conn,
427 const svn_string_t *str);
429 /** Write a cstring over the net.
431 * Writes will be buffered until the next read or flush.
433 * @deprecated Provided for backward compatibility with the 1.7 API.
434 * RA_SVN low-level functions are no longer considered public.
438 svn_ra_svn_write_cstring(svn_ra_svn_conn_t *conn,
442 /** Write a word over the net.
444 * Writes will be buffered until the next read or flush.
446 * @deprecated Provided for backward compatibility with the 1.7 API.
447 * RA_SVN low-level functions are no longer considered public.
451 svn_ra_svn_write_word(svn_ra_svn_conn_t *conn,
455 /** Write a list of properties over the net. @a props is allowed to be NULL,
456 * in which case an empty list will be written out.
460 * @deprecated Provided for backward compatibility with the 1.7 API.
461 * RA_SVN low-level functions are no longer considered public.
465 svn_ra_svn_write_proplist(svn_ra_svn_conn_t *conn,
469 /** Begin a list. Writes will be buffered until the next read or flush.
471 * @deprecated Provided for backward compatibility with the 1.7 API.
472 * RA_SVN low-level functions are no longer considered public.
476 svn_ra_svn_start_list(svn_ra_svn_conn_t *conn,
479 /** End a list. Writes will be buffered until the next read or flush.
481 * @deprecated Provided for backward compatibility with the 1.7 API.
482 * RA_SVN low-level functions are no longer considered public.
486 svn_ra_svn_end_list(svn_ra_svn_conn_t *conn,
489 /** Flush the write buffer.
491 * Normally this shouldn't be necessary, since the write buffer is flushed
492 * when a read is attempted.
494 * @deprecated Provided for backward compatibility with the 1.7 API.
495 * RA_SVN low-level functions are no longer considered public.
499 svn_ra_svn_flush(svn_ra_svn_conn_t *conn,
502 /** Write a tuple, using a printf-like interface.
504 * The format string @a fmt may contain:
507 Spec Argument type Item type
508 ---- -------------------- ---------
509 n apr_uint64_t Number
510 r svn_revnum_t Number
511 s const svn_string_t * String
512 c const char * String
514 b svn_boolean_t Word ("true" or "false")
517 ? Remaining elements optional
518 ! (at beginning or end) Suppress opening or closing of tuple
521 * Inside the optional part of a tuple, 'r' values may be @c
522 * SVN_INVALID_REVNUM, 'n' values may be
523 * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', and 'w' values may be
524 * @c NULL; in these cases no data will be written. 'b' and '(' may
525 * not appear in the optional part of a tuple. Either all or none of
526 * the optional values should be valid.
528 * (If we ever have a need for an optional boolean value, we should
529 * invent a 'B' specifier which stores a boolean into an int, using -1
530 * for unspecified. Right now there is no need for such a thing.)
532 * Use the '!' format specifier to write partial tuples when you have
533 * to transmit an array or other unusual data. For example, to write
534 * a tuple containing a revision, an array of words, and a boolean:
536 SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));
537 for (i = 0; i < n; i++)
538 SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));
539 SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endcode
541 * @deprecated Provided for backward compatibility with the 1.7 API.
542 * RA_SVN low-level functions are no longer considered public.
546 svn_ra_svn_write_tuple(svn_ra_svn_conn_t *conn,
548 const char *fmt, ...);
550 /** Read an item from the network into @a *item.
552 * @deprecated Provided for backward compatibility with the 1.7 API.
553 * RA_SVN low-level functions are no longer considered public.
557 svn_ra_svn_read_item(svn_ra_svn_conn_t *conn,
559 svn_ra_svn_item_t **item);
561 /** Scan data on @a conn until we find something which looks like the
562 * beginning of an svn server greeting (an open paren followed by a
563 * whitespace character). This function is appropriate for beginning
564 * a client connection opened in tunnel mode, since people's dotfiles
565 * sometimes write output to stdout. It may only be called at the
566 * beginning of a client connection.
568 * @deprecated Provided for backward compatibility with the 1.7 API.
569 * RA_SVN low-level functions are no longer considered public.
573 svn_ra_svn_skip_leading_garbage(svn_ra_svn_conn_t *conn,
576 /** Parse an array of @c svn_sort__item_t structures as a tuple, using a
577 * printf-like interface. The format string @a fmt may contain:
580 Spec Argument type Item type
581 ---- -------------------- ---------
582 n apr_uint64_t * Number
583 r svn_revnum_t * Number
584 s svn_string_t ** String
585 c const char ** String
587 b svn_boolean_t * Word ("true" or "false")
588 B apr_uint64_t * Word ("true" or "false")
589 l apr_array_header_t ** List
592 ? Tuple is allowed to end here
595 * Note that a tuple is only allowed to end precisely at a '?', or at
596 * the end of the specification. So if @a fmt is "c?cc" and @a list
597 * contains two elements, an error will result.
599 * 'B' is similar to 'b', but may be used in the optional tuple specification.
600 * It returns TRUE, FALSE, or SVN_RA_SVN_UNSPECIFIED_NUMBER.
602 * If an optional part of a tuple contains no data, 'r' values will be
603 * set to @c SVN_INVALID_REVNUM, 'n' and 'B' values will be set to
604 * SVN_RA_SVN_UNSPECIFIED_NUMBER, and 's', 'c', 'w', and 'l' values
605 * will be set to @c NULL. 'b' may not appear inside an optional
606 * tuple specification; use 'B' instead.
608 * @deprecated Provided for backward compatibility with the 1.7 API.
609 * RA_SVN low-level functions are no longer considered public.
613 svn_ra_svn_parse_tuple(const apr_array_header_t *list,
615 const char *fmt, ...);
617 /** Read a tuple from the network and parse it as a tuple, using the
618 * format string notation from svn_ra_svn_parse_tuple().
620 * @deprecated Provided for backward compatibility with the 1.7 API.
621 * RA_SVN low-level functions are no longer considered public.
625 svn_ra_svn_read_tuple(svn_ra_svn_conn_t *conn,
627 const char *fmt, ...);
629 /** Parse an array of @c svn_ra_svn_item_t structures as a list of
630 * properties, storing the properties in a hash table.
634 * @deprecated Provided for backward compatibility with the 1.7 API.
635 * RA_SVN low-level functions are no longer considered public.
639 svn_ra_svn_parse_proplist(const apr_array_header_t *list,
643 /** Read a command response from the network and parse it as a tuple, using
644 * the format string notation from svn_ra_svn_parse_tuple().
646 * @deprecated Provided for backward compatibility with the 1.7 API.
647 * RA_SVN low-level functions are no longer considered public.
651 svn_ra_svn_read_cmd_response(svn_ra_svn_conn_t *conn,
653 const char *fmt, ...);
655 /** Accept commands over the network and handle them according to @a
656 * commands. Command handlers will be passed @a conn, a subpool of @a
657 * pool (cleared after each command is handled), the parameters of the
658 * command, and @a baton. Commands will be accepted until a
659 * terminating command is received (a command with "terminate" set in
660 * the command table). If a command handler returns an error wrapped
661 * in SVN_RA_SVN_CMD_ERR (see the @c SVN_CMD_ERR macro), the error
662 * will be reported to the other side of the connection and the
663 * command loop will continue; any other kind of error (typically a
664 * network or protocol error) is passed through to the caller.
668 * @deprecated Provided for backward compatibility with the 1.7 API.
669 * RA_SVN low-level functions are no longer considered public.
673 svn_ra_svn_handle_commands2(svn_ra_svn_conn_t *conn,
675 const svn_ra_svn_cmd_entry_t *commands,
677 svn_boolean_t error_on_disconnect);
679 /** Similar to svn_ra_svn_handle_commands2 but @a error_on_disconnect
680 * is always @c FALSE.
682 * @deprecated Provided for backward compatibility with the 1.5 API.
686 svn_ra_svn_handle_commands(svn_ra_svn_conn_t *conn,
688 const svn_ra_svn_cmd_entry_t *commands,
691 /** Write a command over the network, using the same format string notation
692 * as svn_ra_svn_write_tuple().
694 * @deprecated Provided for backward compatibility with the 1.7 API.
695 * RA_SVN low-level functions are no longer considered public.
699 svn_ra_svn_write_cmd(svn_ra_svn_conn_t *conn,
702 const char *fmt, ...);
704 /** Write a successful command response over the network, using the
705 * same format string notation as svn_ra_svn_write_tuple(). Do not use
706 * partial tuples with this function; if you need to use partial
707 * tuples, just write out the "success" and argument tuple by hand.
709 * @deprecated Provided for backward compatibility with the 1.7 API.
710 * RA_SVN low-level functions are no longer considered public.
714 svn_ra_svn_write_cmd_response(svn_ra_svn_conn_t *conn,
716 const char *fmt, ...);
718 /** Write an unsuccessful command response over the network.
720 * @deprecated Provided for backward compatibility with the 1.7 API.
721 * RA_SVN low-level functions are no longer considered public.
725 svn_ra_svn_write_cmd_failure(svn_ra_svn_conn_t *conn,
735 #endif /* __cplusplus */
737 #endif /* SVN_RA_SVN_H */