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. |
|