Troubles with using the GOLANG SDK

Hi,

I have been studying the Ziti GOLANG SDK and working through the code samples and have some feedback and questions.

  1. zping latency issue
    The behaviour of the zping example was not as expected.
    We setup two services on the same VM and attempted to zping between them. While this worked, we consistently saw ping times of > 400ms. We confirmed this was due to our edge router running in the US and the zpings apparently travelling via the US edge router each time. Our return ping time to the US is around 200ms so this indicates two return trips for each zping. We confirmed this was the cause by creating a new local edge router and the ping times went down (but still appeared twice as high as regular pings). Can you please confirm this is expected behaviour?

  2. Documentation
    For many of the examples no documentation or comments were included to explain what the sample was doing, how to configure it or how to execute it. For all but two of them we eventually worked it out through trial and error and/or examining the go code. Much effort could be saved by simply adding a readme for each example.

A good example is in the main readme where it states simply:
“SDK is using ZITI_SDK_CONFIG environment variable to load configuration file.”
But no examples are provided nor an explanation of what a “configuration file” is. I eventually realised this was a JSON identification file but it was far from obvious. I also found that this statement is not true for some of the examples and use of the environment variable was not consitent.

  1. Specific comments on each example

3.1 Reflect
No complaints, documentation was fine, and was quick to set up

3.2 chat-client & chat-server
No documentation

‘unable to configure ziti as config environment variable ZITI_SDK_CONFIG not populated’ error. See above. There is no instructions on how to setup this environment variable and what it is meant to point to.
While I eventually got it working and guessed the configuration file actually meant an identity JSON file, it was by no means obvious. Adding an extra paragraph explaining this with an example in the readme would assist others - especially those less experienced in NetFoundry ZTA.

The chat-server has a CLI override for choosing the service name whereas the chat-client has no override and the name is hard coded. This an annoying inconsitency and required a code change.

3.3 simple-server
No documentation
What sort of simple server? It took a while for me to figure out it was a HTTP server and what URL expected me to use it.
Just a readme or a few lines of comments would have helped.

3.4 curlz
No documentation
After trial and error, I figured out it was expecting to connect to a ziti web server. Pointed it to the simple-server and it worked.

3.5 grpc-example
There was documentation, but it was incorrect in the formatting for the command line arguments. The docs said to use plain text like the previous examples, but it actually needed flags to be passed through the CLI.
Did not fallback to the ZITI_SDK_CONFIG environment variable which was inconsistent with the other examples
The default timeout (deadline of 1 second) wasn’t enough to run the script without timing out. This had to be fixed by upping the timeout in the script. This was probably because our edge router is in the U.S, while both the server and client are in Australia. The communication latency would account for this. Still, an argument to set or override timeout should be there.

3.6 zping
Documentation was good and included information on how to set up the right environment for the script from scratch.
The network.png diagram could be clearer, but I’m thankful for having it
The set up instructions were daunting and a simplified version could be made for people who have a pre-existing ziti network, as that cut out all but 2 of the steps
The example output in the readme has the line ‘INFO[0000] connection to edge router using token’, which I never saw, but the ping worked. Could this be explained?
The client and server modes have lots of possible flags which aren’t mentioned at all in the readme. I know you can use ‘-h’, but it would be better if the options are properly documented
The script has a ‘completion’ mode that also isn’t mentioned at all, but is present in the help menu. I also couldn’t find in the code where this mode comes from.

3.7 call
No documentation
Unable to understand what client it’s expecting to connect
Needs a list of the possible commands, what they do, and the appropriate times to use them
When using /call, it would ‘call’… something. Then say 'connected to ', missing whatever it was connected to

3.8 zcat
No documentation
The main error I saw was ‘service {service ID} has no terminators’. I saw this on the ‘reflect’ script when it was expecting a server on the other end, but zcat doesn’t have a server mode
Unable to understand what exactly it was looking for. Trying to run vanilla netcat listeners on the service didn’t work.

1 Like

@Dacilla welcome to the community and thanks so much for this excellent feedback! We’ll take a look at your feedback in detail and get it figured out.

We’re definitely aware we need some documentation on these examples and really appreciate you taking the time to work through them. I’ll be going through your comments and creating issues on GitHub to get these addressed.

Hi @Dacilla, I wanted to provide an update on the feedback you gave us. I’ve linked each concern pointing you to the issue created for that concern as well as a brief summary on the current status for each issue.

  1. :wrench: zping latency issue - Currently being looked at

  2. Documentation
    For the issue regarding the use of ZITI_SDK_CONFIG; this environment variable name is confusing and knowing that it needs to be set is not straight forward so all examples are being updated to provide the identity file as an argument instead of using the environment variable. When not provided, an error message clearly explains that the identity file needs to be provided as an argument.

  3. Specific comments on each example
    3.1 :white_check_mark: Reflect
    No changes as you stated, documentation was sufficient.
    3.2 :white_check_mark: chat-client & chat-server
    Documentation for this example has been created
    3.3 :white_check_mark: simple-server
    Documentation for this example is being created, a PR can be seen here
    3.4 :white_check_mark: curlz
    Documentation for this example has been created
    3.5 :white_check_mark: grpc-example
    Documentation for this example has been updated
    3.6 :clock1: zping
    An issue has been created to check the output and update if needed.
    3.7 :white_check_mark: call
    Documentation for this example has been created
    3.8 :white_check_mark: zcat
    An issue has been created to add documentation, currently being worked on

Again, your feedback is very much appreciated and we’re happy to get these issues resolved to help future users, thank you again.

Please let us know if you have any more questions or concerns.

1 Like

Hi Dacilla with regard to you feedback on zping. Identities have to connect through at least one ziti edge-router so assuming both identities have the US edge-router in common and it has been selected as the closest edge router by the client identity then all traffic flows through that edge router which means the zping has to travel 100ms to reach the edge-router from the client identity then 100ms from the edge-router to the hosting identity the reply then has to traverse 100ms back to the edge-router and then another 100ms back to the client identity on the final leg. That is 400ms total.

@Dacilla Just one last update, I’ve updated my last post to show the current status of the issues created based on your feedback. All issues have been addressed with one to two being currently looked at and the rest fixed.

Also, on Ziti TV this past Friday, @TheLumberjack went through a few of the examples with the new documentation.

If you want the video link: