Mercurial > hg
comparison mercurial/help/internals/wireprotocol.txt @ 39439:dc61a67c1fc0
internals: extract wire protocol version 2 commands to standalone doc
wireprotocol.txt is a bit long and unwieldy. I think splitting it up
will help aid comprehension.
Let's start by extracting wire protocol version 2 commands to a
standalone document.
As part of the port, I munged with the section titles a bit and
expanded the TODO around node namespaces.
Differential Revision: https://phab.mercurial-scm.org/D4442
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Thu, 23 Aug 2018 13:11:13 -0700 |
parents | 0c184ca594bb |
children | b0e0db1565d1 |
comparison
equal
deleted
inserted
replaced
39438:c734a5c82f38 | 39439:dc61a67c1fc0 |
---|---|
1376 Commands | 1376 Commands |
1377 ======== | 1377 ======== |
1378 | 1378 |
1379 This section contains a list of all wire protocol commands implemented by | 1379 This section contains a list of all wire protocol commands implemented by |
1380 the canonical Mercurial server. | 1380 the canonical Mercurial server. |
1381 | |
1382 See :hg:`help internals.wireprotocolv2` for information on commands exposed | |
1383 to the frame-based protocol. | |
1381 | 1384 |
1382 batch | 1385 batch |
1383 ----- | 1386 ----- |
1384 | 1387 |
1385 Issue multiple commands while sending a single command request. The purpose | 1388 Issue multiple commands while sending a single command request. The purpose |
1748 case, the response type is ``stream``. For the HTTP version 1 transport, the | 1751 case, the response type is ``stream``. For the HTTP version 1 transport, the |
1749 response is zlib compressed. | 1752 response is zlib compressed. |
1750 | 1753 |
1751 The server may also respond with a generic error type, which contains a string | 1754 The server may also respond with a generic error type, which contains a string |
1752 indicating the failure. | 1755 indicating the failure. |
1753 | |
1754 Frame-Based Protocol Commands | |
1755 ============================= | |
1756 | |
1757 **Experimental and under active development** | |
1758 | |
1759 This section documents the wire protocol commands exposed to transports | |
1760 using the frame-based protocol. The set of commands exposed through | |
1761 these transports is distinct from the set of commands exposed to legacy | |
1762 transports. | |
1763 | |
1764 The frame-based protocol uses CBOR to encode command execution requests. | |
1765 All command arguments must be mapped to a specific or set of CBOR data | |
1766 types. | |
1767 | |
1768 The response to many commands is also CBOR. There is no common response | |
1769 format: each command defines its own response format. | |
1770 | |
1771 TODO require node type be specified, as N bytes of binary node value | |
1772 could be ambiguous once SHA-1 is replaced. | |
1773 | |
1774 branchmap | |
1775 --------- | |
1776 | |
1777 Obtain heads in named branches. | |
1778 | |
1779 Receives no arguments. | |
1780 | |
1781 The response is a map with bytestring keys defining the branch name. | |
1782 Values are arrays of bytestring defining raw changeset nodes. | |
1783 | |
1784 capabilities | |
1785 ------------ | |
1786 | |
1787 Obtain the server's capabilities. | |
1788 | |
1789 Receives no arguments. | |
1790 | |
1791 This command is typically called only as part of the handshake during | |
1792 initial connection establishment. | |
1793 | |
1794 The response is a map with bytestring keys defining server information. | |
1795 | |
1796 The defined keys are: | |
1797 | |
1798 commands | |
1799 A map defining available wire protocol commands on this server. | |
1800 | |
1801 Keys in the map are the names of commands that can be invoked. Values | |
1802 are maps defining information about that command. The bytestring keys | |
1803 are: | |
1804 | |
1805 args | |
1806 A map of argument names and their expected types. | |
1807 | |
1808 Types are defined as a representative value for the expected type. | |
1809 e.g. an argument expecting a boolean type will have its value | |
1810 set to true. An integer type will have its value set to 42. The | |
1811 actual values are arbitrary and may not have meaning. | |
1812 permissions | |
1813 An array of permissions required to execute this command. | |
1814 | |
1815 compression | |
1816 An array of maps defining available compression format support. | |
1817 | |
1818 The array is sorted from most preferred to least preferred. | |
1819 | |
1820 Each entry has the following bytestring keys: | |
1821 | |
1822 name | |
1823 Name of the compression engine. e.g. ``zstd`` or ``zlib``. | |
1824 | |
1825 framingmediatypes | |
1826 An array of bytestrings defining the supported framing protocol | |
1827 media types. Servers will not accept media types not in this list. | |
1828 | |
1829 rawrepoformats | |
1830 An array of storage formats the repository is using. This set of | |
1831 requirements can be used to determine whether a client can read a | |
1832 *raw* copy of file data available. | |
1833 | |
1834 heads | |
1835 ----- | |
1836 | |
1837 Obtain DAG heads in the repository. | |
1838 | |
1839 The command accepts the following arguments: | |
1840 | |
1841 publiconly (optional) | |
1842 (boolean) If set, operate on the DAG for public phase changesets only. | |
1843 Non-public (i.e. draft) phase DAG heads will not be returned. | |
1844 | |
1845 The response is a CBOR array of bytestrings defining changeset nodes | |
1846 of DAG heads. The array can be empty if the repository is empty or no | |
1847 changesets satisfied the request. | |
1848 | |
1849 TODO consider exposing phase of heads in response | |
1850 | |
1851 known | |
1852 ----- | |
1853 | |
1854 Determine whether a series of changeset nodes is known to the server. | |
1855 | |
1856 The command accepts the following arguments: | |
1857 | |
1858 nodes | |
1859 (array of bytestrings) List of changeset nodes whose presence to | |
1860 query. | |
1861 | |
1862 The response is a bytestring where each byte contains a 0 or 1 for the | |
1863 corresponding requested node at the same index. | |
1864 | |
1865 TODO use a bit array for even more compact response | |
1866 | |
1867 listkeys | |
1868 -------- | |
1869 | |
1870 List values in a specified ``pushkey`` namespace. | |
1871 | |
1872 The command receives the following arguments: | |
1873 | |
1874 namespace | |
1875 (bytestring) Pushkey namespace to query. | |
1876 | |
1877 The response is a map with bytestring keys and values. | |
1878 | |
1879 TODO consider using binary to represent nodes in certain pushkey namespaces. | |
1880 | |
1881 lookup | |
1882 ------ | |
1883 | |
1884 Try to resolve a value to a changeset revision. | |
1885 | |
1886 Unlike ``known`` which operates on changeset nodes, lookup operates on | |
1887 node fragments and other names that a user may use. | |
1888 | |
1889 The command receives the following arguments: | |
1890 | |
1891 key | |
1892 (bytestring) Value to try to resolve. | |
1893 | |
1894 On success, returns a bytestring containing the resolved node. | |
1895 | |
1896 pushkey | |
1897 ------- | |
1898 | |
1899 Set a value using the ``pushkey`` protocol. | |
1900 | |
1901 The command receives the following arguments: | |
1902 | |
1903 namespace | |
1904 (bytestring) Pushkey namespace to operate on. | |
1905 key | |
1906 (bytestring) The pushkey key to set. | |
1907 old | |
1908 (bytestring) Old value for this key. | |
1909 new | |
1910 (bytestring) New value for this key. | |
1911 | |
1912 TODO consider using binary to represent nodes is certain pushkey namespaces. | |
1913 TODO better define response type and meaning. |