From 3d5565f0e9539bf629abfe2428f16281cfc67e46 Mon Sep 17 00:00:00 2001
From: folex <0xdxdy@gmail.com>
Date: Fri, 26 Aug 2022 11:07:08 +0400
Subject: [PATCH] BREAKING CHANGE: Fix get_contact, clarify connect and
 is_connected docs (#27)

---
 .github/workflows/check.yml   |  4 ++--
 .github/workflows/release.yml |  6 ++---
 builtin.aqua                  | 44 ++++++++++++++++++++++-------------
 3 files changed, 33 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 2254161..4e90a98 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -21,11 +21,11 @@ jobs:
             key: ${{ runner.os }}-v1-node-${{ hashFiles('**/package-lock.json') }}
             restore-keys: |
                 ${{ runner.os }}-v1-node
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v1
         with:
-            node-version: 14
+            node-version: 16
 
       - name: Install aqua compiler
         run: npm install -g @fluencelabs/aqua
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 24d567a..cded666 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,11 +26,11 @@ jobs:
             key: ${{ runner.os }}-v1-node-${{ hashFiles('**/package-lock.json') }}
             restore-keys: |
                 ${{ runner.os }}-v1-node
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v1
         with:
-            node-version: 14
+            node-version: 16
 
       - name: Install aqua compiler
         run: npm install -g @fluencelabs/aqua
@@ -41,7 +41,7 @@ jobs:
       ### Publish to NPM registry
       - uses: actions/setup-node@v1
         with:
-          node-version: "14"
+          node-version: "16"
           registry-url: "https://registry.npmjs.org"
 
       - name: Publish to NPM
diff --git a/builtin.aqua b/builtin.aqua
index b7d0697..2542a92 100644
--- a/builtin.aqua
+++ b/builtin.aqua
@@ -107,22 +107,6 @@ service Op("op"):
     concat_strings(a: string, b: string) -> string
 
 service Peer("peer"):
-    -- Checks if there is a direct connection to the peer identified by a given PeerId
-    -- Argument: PeerId – id of the peer to check if there's a connection with
-    -- Returns: bool - true if connected to the peer, false otherwise
-    is_connected(peer: PeerId) -> bool
-
-    -- Initiates a connection to the specified peer
-    -- Arguments:
-    --  id - id of the target peer
-    --  multiaddrs – an array of target peer's addresses
-    -- Returns: bool - true if connection was successful
-    connect(id: PeerId, multiaddrs: ?[]string) -> bool
-    -- Resolves the contact of a peer via Kademlia
-    -- Argument: PeerId – id of the target peer
-    -- Returns: Contact - true if connection was successful
-    get_contact(peer: PeerId) -> Contact
-
     -- Get information about the peer
     identify() -> Info
 
@@ -136,6 +120,34 @@ service Peer("peer"):
     -- message is returned after duration has passed
     timeout(duration_ms: u64, message: string) -> string
 
+    ---- Low level functions for accessing connection pool
+
+    -- Checks if there is a direct connection to the peer identified by a given PeerId
+    -- Argument: PeerId – id of the peer to check if there's a connection with
+    -- Returns: bool - true if connected to the peer, false otherwise
+    -- NOTE:
+    --  This is a very low-level function, it most likely won't fit your goals.
+    --  It's almost always better to use race pattern to check connectivity.
+    --  See https://doc.fluence.dev/aqua-book/language/flow/parallel#timeout-and-race-patterns
+    is_connected(peer: PeerId) -> bool
+
+    -- Initiates a connection to the specified peer
+    -- Arguments:
+    --  id - id of the target peer
+    --  multiaddrs – an array of target peer's addresses
+    -- Returns: bool - true if connection was successful
+    -- NOTE:
+    --  This is a low-level function, it most likely won't fit your goals.
+    --  Most often you just need to use `on id:` and connection will be established automatically.
+    connect(id: PeerId, multiaddrs: []string) -> bool
+
+    -- Returns known multiaddresses of a peer
+    -- Argument: PeerId – id of the target peer
+    -- Returns:
+    --  Contact - if target peer is connected to current peer,
+    --  return data structure with multiaddresses inside, and nil otherwise.
+    get_contact(peer: PeerId) -> ?Contact
+
 service Kademlia("kad"):
     -- Instructs node to return the locally-known nodes
     -- in the Kademlia neighborhood for a given key