##// END OF EJS Templates
wireprotov2: define semantics for content redirects...
Gregory Szorc -
r40058:33eb670e default
parent child Browse files
Show More
@@ -115,6 +115,22 b' args'
115 115 Each command defines its own set of argument names and their expected
116 116 types.
117 117
118 redirect (optional)
119 (map) Advertises client support for following response *redirects*.
120
121 This map has the following bytestring keys:
122
123 targets
124 (array of bytestring) List of named redirect targets supported by
125 this client. The names come from the targets advertised by the
126 server's *capabilities* message.
127
128 hashes
129 (array of bytestring) List of preferred hashing algorithms that can
130 be used for content integrity verification.
131
132 See the *Content Redirects* section below for more on content redirects.
133
118 134 This frame type MUST ONLY be sent from clients to servers: it is illegal
119 135 for a server to send this frame to a client.
120 136
@@ -506,6 +522,9 b' status'
506 522 error
507 523 There was an error processing the command. More details about the
508 524 error are encoded in the ``error`` key.
525 redirect
526 The response for this command is available elsewhere. Details on
527 where are in the ``location`` key.
509 528
510 529 error (optional)
511 530 A map containing information about an encountered error. The map has the
@@ -515,5 +534,116 b' error (optional)'
515 534 (array of maps) A message describing the error. The message uses the
516 535 same format as those in the ``Human Output Side-Channel`` frame.
517 536
537 location (optional)
538 (map) Presence indicates that a *content redirect* has occurred. The map
539 provides the external location of the content.
540
541 This map contains the following bytestring keys:
542
543 url
544 (bytestring) URL from which this content may be requested.
545
546 mediatype
547 (bytestring) The media type for the fetched content. e.g.
548 ``application/mercurial-*``.
549
550 In some transports, this value is also advertised by the transport.
551 e.g. as the ``Content-Type`` HTTP header.
552
553 size (optional)
554 (unsigned integer) Total size of remote object in bytes. This is
555 the raw size of the entity that will be fetched, minus any
556 non-Mercurial protocol encoding (e.g. HTTP content or transfer
557 encoding.)
558
559 fullhashes (optional)
560 (array of arrays) Content hashes for the entire payload. Each entry
561 is an array of bytestrings containing the hash name and the hash value.
562
563 fullhashseed (optional)
564 (bytestring) Optional seed value to feed into hasher for full content
565 hash verification.
566
567 serverdercerts (optional)
568 (array of bytestring) DER encoded x509 certificates for the server. When
569 defined, clients MAY validate that the x509 certificate on the target
570 server exactly matches the certificate used here.
571
572 servercadercerts (optional)
573 (array of bytestring) DER encoded x509 certificates for the certificate
574 authority of the target server. When defined, clients MAY validate that
575 the x509 on the target server was signed by CA certificate in this set.
576
577 # TODO support for giving client an x509 certificate pair to be used as a
578 # client certificate.
579
580 # TODO support common authentication mechanisms (e.g. HTTP basic/digest
581 # auth).
582
583 # TODO support custom authentication mechanisms. This likely requires
584 # server to advertise required auth mechanism so client can filter.
585
586 # TODO support chained hashes. e.g. hash for each 1MB segment so client
587 # can iteratively validate data without having to consume all of it first.
588
518 589 TODO formalize when error frames can be seen and how errors can be
519 590 recognized midway through a command response.
591
592 Content Redirects
593 =================
594
595 Servers have the ability to respond to ANY command request with a
596 *redirect* to another location. Such a response is referred to as a *redirect
597 response*. (This feature is conceptually similar to HTTP redirects, but is
598 more powerful.)
599
600 A *redirect response* MUST ONLY be issued if the client advertises support
601 for a redirect *target*.
602
603 A *redirect response* MUST NOT be issued unless the client advertises support
604 for one.
605
606 Clients advertise support for *redirect responses* after looking at the server's
607 *capabilities* data, which is fetched during initial server connection
608 handshake. The server's capabilities data advertises named *targets* for
609 potential redirects.
610
611 Each target is described by a protocol name, connection and protocol features,
612 etc. The server also advertises target-agnostic redirect settings, such as
613 which hash algorithms are supported for content integrity checking. (See
614 the documentation for the *capabilities* command for more.)
615
616 Clients examine the set of advertised redirect targets for compatibility.
617 When sending a command request, the client advertises the set of redirect
618 target names it is willing to follow, along with some other settings influencing
619 behavior.
620
621 For example, say the server is advertising a ``cdn`` redirect target that
622 requires SNI and TLS 1.2. If the client supports those features, it will
623 send command requests stating that the ``cdn`` target is acceptable to use.
624 But if the client doesn't support SNI or TLS 1.2 (or maybe it encountered an
625 error using this target from a previous request), then it omits this target
626 name.
627
628 If the client advertises support for a redirect target, the server MAY
629 substitute the normal, inline response data for a *redirect response* -
630 one where the initial CBOR map has a ``status`` key with value ``redirect``.
631
632 The *redirect response* at a minimum advertises the URL where the response
633 can be retrieved.
634
635 The *redirect response* MAY also advertise additional details about that
636 content and how to retrieve it. Notably, the response may contain the
637 x509 public certificates for the server being redirected to or the
638 certificate authority that signed that server's certificate. Unless the
639 client has existing settings that offer stronger trust validation than what
640 the server advertises, the client SHOULD use the server-provided certificates
641 when validating the connection to the remote server in place of any default
642 connection verification checks. This is because certificates coming from
643 the server SHOULD establish a stronger chain of trust than what the default
644 certification validation mechanism in most environments provides. (By default,
645 certificate validation ensures the signer of the cert chains up to a set of
646 trusted root certificates. And if an explicit certificate or CA certificate
647 is presented, that greadly reduces the set of certificates that will be
648 recognized as valid, thus reducing the potential for a "bad" certificate
649 to be used and trusted.)
@@ -111,6 +111,38 b' rawrepoformats'
111 111 requirements can be used to determine whether a client can read a
112 112 *raw* copy of file data available.
113 113
114 redirect
115 A map declaring potential *content redirects* that may be used by this
116 server. Contains the following bytestring keys:
117
118 targets
119 (array of maps) Potential redirect targets. Values are maps describing
120 this target in more detail. Each map has the following bytestring keys:
121
122 name
123 (bytestring) Identifier for this target. The identifier will be used
124 by clients to uniquely identify this target.
125
126 protocol
127 (bytestring) High-level network protocol. Values can be
128 ``http``, ```https``, ``ssh``, etc.
129
130 uris
131 (array of bytestrings) Representative URIs for this target.
132
133 snirequired (optional)
134 (boolean) Indicates whether Server Name Indication is required
135 to use this target. Defaults to False.
136
137 tlsversions (optional)
138 (array of bytestring) Indicates which TLS versions are supported by
139 this target. Values are ``1.1``, ``1.2``, ``1.3``, etc.
140
141 hashes
142 (array of bytestring) Indicates support for hashing algorithms that are
143 used to ensure content integrity. Values include ``sha1``, ``sha256``,
144 etc.
145
114 146 changesetdata
115 147 -------------
116 148
General Comments 0
You need to be logged in to leave comments. Login now