Document upcoming changes in 1.7 net.box

[mejedi]

tarantool/tarantool@3b81e95

• formerly, net.box could work both over Binary and Lua console protocols. Support for Lua console was dropped. Anyway, when the protocol was Lua console, 99% of net.box features didn't work;

• dropped :console() method in net.box (which was undocumented anyway);

• added :wait_state() method, ex:

  cn:wait_state('active')
  cn:wait_state('active', 1.5) -- timeout 1.5 secs
  cn:wait_state({active=true, fetch_schema=true}) -- waiting for either `active` or `fetch_schema` states

  returns true if target state was reached, false otherwise (timeout or connection closed;)

• please document states and transitions (see https://github.com/tarantool/tarantool/blob/1.7/src/box/lua/net_box.lua#L106)

• added call_16 option in net.box.connect (Eval-style marshalling in IPROTO_CALL (1.7) tarantool#1296);

• please document wait_connected option (by default connect() blocks until the connection is established, passing wait_connected=false makes it return immediately; also: wait_connected=1.5 makes it wait at most 1.5 secs before returning);

Breaking changes

Ideally, there should be one dedicated page, that lists breaking changes for the particular release and provides migration instruction. Concerning net.box, the breaking changes are:

• internals changed, code depending on undocumented internals WILL break;
• :wait_connected() returns true, as the docs say (formerly, it returned active/closed;)
• CALL_16 (linked above). New and old call semantics are incompatible in subtle ways. It is suggested to follow this update procedure:
  1. Update code first. Add call_16=true in net.box.connect() options. This step ensures that semantics won't change when new Tarantool is deployed. This option is ignored by older Tarantool.
  2. Update Tarantool.
  3. Ensure that all servers connections are made to are running 1.7. Older servers don't implement new CALL semantics and an attempt to make a «new» call will result in connection termination.
  4. Remove call_16=true added during step Upload web-site directly to Amazon S3 / CloudFront #1.