[glib: 1/2] guri: Document and check restrictions on path prefixes

[Sebastian Dröge <sdroege src gnome org>]

commit 89cf298b1968db31702adf72c2fbc1b522120f41
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Aug 7 13:15:52 2020 +0100

    guri: Document and check restrictions on path prefixes
    
    RFC 3986, section 3 says:
    > The scheme and path components are required, though the path may be
    > empty (no characters).  When authority is present, the path must
    > either be empty or begin with a slash ("/") character.  When
    > authority is not present, the path cannot begin with two slash
    > characters ("//").  These restrictions result in five different ABNF
    > rules for a path (Section 3.3), only one of which will match any
    > given URI reference.
    
    (See https://tools.ietf.org/html/rfc3986#section-3.)
    
    Given that those conditions are almost always going to be true, and that
    typically the number and form of arguments passed to g_uri_join() will
    be known at compile time, it would be unnecessarily awkward to add a
    `GError` argument to g_uri_join() to detect these situations.
    
    Instead, add precondition checks and document the restrictions.
    Developers are responsible for ensuring their paths are in the right
    format themselves.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/guri.c | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)
---
diff --git a/glib/guri.c b/glib/guri.c
index ee10a23eb..b8136d0b5 100644
--- a/glib/guri.c
+++ b/glib/guri.c
@@ -1347,6 +1347,13 @@ g_uri_join_internal (GUriFlags    flags,
   gboolean encoded = (flags & G_URI_FLAGS_ENCODED);
   GString *str;
 
+  /* Restrictions on path prefixes. See:
+   * https://tools.ietf.org/html/rfc3986#section-3
+   */
+  g_return_val_if_fail (path != NULL, NULL);
+  g_return_val_if_fail (host == NULL || (path[0] == '\0' || path[0] == '/'), NULL);
+  g_return_val_if_fail (host != NULL || (path[0] != '/' || path[1] != '/'), NULL);
+
   str = g_string_new (scheme);
   if (scheme)
     g_string_append_c (str, ':');
@@ -1455,6 +1462,11 @@ g_uri_join_internal (GUriFlags    flags,
  * Joins the given components together according to @flags to create
  * an absolute URI string. @path may not be %NULL (though it may be "").
  *
+ * When @host is present, @path must either be empty or begin with a slash (`/`)
+ * character. When @host is not present, @path cannot begin with two slash
+   characters (`//`). See
+ * [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
+ *
  * See also g_uri_join_with_user(), which allows specifying the
  * components of the "userinfo" separately.
  *
@@ -1504,7 +1516,7 @@ g_uri_join (GUriFlags    flags,
  * an absolute URI string. @path may not be %NULL (though it may be "").
  *
  * In contrast to g_uri_join(), this allows specifying the components
- * of the "userinfo" separately.
+ * of the "userinfo" separately. It otherwise behaves the same.
  *
  * Return value: an absolute URI string
  *