1# Open Connection (opcode 0x50)
2
3Sent by an external entity to a producer or a consumer to create a logical channel.
4
5The request:
6
7* Must have an 8 byte extras section
8* Must have key
9* Can optionally have a value
10
11Extra looks like:
12
13     Byte/     0       |       1       |       2       |       3       |
14        /              |               |               |               |
15       |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
16       +---------------+---------------+---------------+---------------+
17      0| Reserved                                                      |
18       +---------------+---------------+---------------+---------------+
19      4| flags                                                         |
20       +---------------+---------------+---------------+---------------+
21
22Flags are specified as a bitmask in network byte order with the following bits defined:
23
24* 0x1: __DCP type__ requests a producer is created, if this bit is clear a consumer
25  is created (unless the notifier bit is set).
26* 0x2: __DCP notifier__ request a 'notifier', cannot be combined with 0x1.
27* 0x4: __Include XATTRs__ requests that DCP_MUTATION, DCP_DELETION and DCP_EXPIRATION
28  (if [enabled](control.md)) messages should include any XATTRs associated with the Document.
29* 0x8: __No value__ requests that DCP_MUTATION, DCP_DELETION and DCP_EXPIRATION
30  (if [enabled](control.md)) messages do not include the Document.
31* 0x20:  __Include delete times__ requests that DCP_DELETION messages include metadata
32  regarding when a document was deleted. When a delete is persisted to disk, it
33  is timestamped and purged from the vbucket after some interval. When 'include
34  delete times' is enabled, deletes which are read from disk will have a
35  timestamp value in the delete-time field, in-memory deletes will have a 0
36  value in the delete-time field. See DCP deletion command. Note when enabled on
37  a consumer, the consumer expects the client to send the delete-time format DCP
38  delete.
39* 0x40: __No value with underlying datatype__. Requests that the server preserves the original
40  datatype when it strips off the document value.
41* 0x100: __Include deleted user xattrs__. Requests that the server includes the document
42  User Xattrs within deletion values.
43
44When setting the Producer or Consumer flag the sender is telling the server what type of connection will be created. For example, if the Producer type is set then the sender of the Open Connection message will be a Consumer.
45
46The connection name is specified using the key field. When selecting a name the only requirement is that the name take up no more space than 256 bytes. It is recommended that the name uses that ASCII character set and uses alpha-numeric characters. It is highly advantageous for improved supportability Couchbase Server that the connection names embed as much contextual information as possible from the client.
47
48As of version 6.5, the _value_ can be used to specify additional information
49about the connection to be opened. If non-empty, the value must be a JSON
50object with the following supported keys:
51
52* `consumer_name` The name the DCP consumer should use to identify itself with
53   the associated DCP producer. Only valid if `DCP type` is `Consumer`.
54
55
56The following example shows the breakdown of the message:
57
58      Byte/     0       |       1       |       2       |       3       |
59         /              |               |               |               |
60        |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
61        +---------------+---------------+---------------+---------------+
62       0| 0x80          | 0x50          | 0x00          | 0x18          |
63        +---------------+---------------+---------------+---------------+
64       4| 0x08          | 0x00          | 0x00          | 0x00          |
65        +---------------+---------------+---------------+---------------+
66       8| 0x00          | 0x00          | 0x00          | 0x20          |
67        +---------------+---------------+---------------+---------------+
68      12| 0x00          | 0x00          | 0x00          | 0x01          |
69        +---------------+---------------+---------------+---------------+
70      16| 0x00          | 0x00          | 0x00          | 0x00          |
71        +---------------+---------------+---------------+---------------+
72      20| 0x00          | 0x00          | 0x00          | 0x00          |
73        +---------------+---------------+---------------+---------------+
74      24| 0x00          | 0x00          | 0x00          | 0x00          |
75        +---------------+---------------+---------------+---------------+
76      28| 0x00          | 0x00          | 0x00          | 0x00          |
77        +---------------+---------------+---------------+---------------+
78      32| 0x62 ('b')    | 0x75 ('u')    | 0x63 ('c')    | 0x6b ('k')    |
79        +---------------+---------------+---------------+---------------+
80      36| 0x65 ('e')    | 0x74 ('t')    | 0x73 ('s')    | 0x74 ('t')    |
81        +---------------+---------------+---------------+---------------+
82      40| 0x72 ('r')    | 0x65 ('e')    | 0x61 ('a')    | 0x6d ('m')    |
83        +---------------+---------------+---------------+---------------+
84      44| 0x20 (' ')    | 0x76 ('v')    | 0x62 ('b')    | 0x5b ('[')    |
85        +---------------+---------------+---------------+---------------+
86      48| 0x31 ('1')    | 0x30 ('0')    | 0x30 ('0')    | 0x2d ('-')    |
87        +---------------+---------------+---------------+---------------+
88      52| 0x31 ('1')    | 0x30 ('0')    | 0x35 ('5')    | 0x5d (']')    |
89        +---------------+---------------+---------------+---------------+
90
91    DCP_OPEN command
92    Field        (offset) (value)
93    Magic        (0)    : 0x80
94    Opcode       (1)    : 0x50
95    Key length   (2,3)  : 0x0018
96    Extra length (4)    : 0x08
97    Data type    (5)    : 0x00
98    Vbucket      (6,7)  : 0x0000
99    Total body   (8-11) : 0x00000020
100    Opaque       (12-15): 0x00000001
101    CAS          (16-23): 0x0000000000000000
102      seqno      (24-27): 0x00000000
103      flags      (28-31): 0x00000000 (consumer)
104    Key          (32-55): bucketstream vb[100-105]
105
106Upon success, the following message is returned.
107
108      Byte/     0       |       1       |       2       |       3       |
109         /              |               |               |               |
110        |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
111        +---------------+---------------+---------------+---------------+
112       0| 0x81          | 0x50          | 0x00          | 0x00          |
113        +---------------+---------------+---------------+---------------+
114       4| 0x00          | 0x00          | 0x00          | 0x00          |
115        +---------------+---------------+---------------+---------------+
116       8| 0x00          | 0x00          | 0x00          | 0x00          |
117        +---------------+---------------+---------------+---------------+
118      12| 0x00          | 0x00          | 0x00          | 0x01          |
119        +---------------+---------------+---------------+---------------+
120      16| 0x00          | 0x00          | 0x00          | 0x00          |
121        +---------------+---------------+---------------+---------------+
122      20| 0x00          | 0x00          | 0x00          | 0x00          |
123        +---------------+---------------+---------------+---------------+
124
125    DCP_OPEN response
126    Field        (offset) (value)
127    Magic        (0)    : 0x81
128    Opcode       (1)    : 0x50
129    Key length   (2,3)  : 0x0000
130    Extra length (4)    : 0x00
131    Data type    (5)    : 0x00
132    Status       (6,7)  : 0x0000
133    Total body   (8-11) : 0x00000000
134    Opaque       (12-15): 0x00000001
135    CAS          (16-23): 0x0000000000000000
136
137**Note:** If the name given in the open connection command is already being used by another established connection then the established connection will be closed and the new connection will be created successfully.
138
139## Collections
140
141If the connection has enabled the collections feature, then the DCP producer or consumer will be collection enabled.
142
143* A DCP producer with collections enabled is the only way to access documents
144  that are not in the default collection.
145* A DCP consumer with collections enabled can accept mutations, deletions and
146  expirations from a collection aware producer.
147
148### Returns
149
150A status code indicating whether or not the operation was successful.
151
152### Errors
153
154**PROTOCOL_BINARY_RESPONSE_EINVAL (0x04)**
155
156If data in this packet is malformed or incomplete then this error is returned.
157
158**(Disconnect)**
159
160If the connection could not be created due to an internal error. Check the server logs if this happens.
161