ceph/src/jaegertracing/thrift/tutorial/netstd/README.md

   1 # Building of samples for different platforms
   2
   3 # Reused components
   4 - NET Core Standard 2.0
   5 - NET Core App 2.0
   6
   7 # How to build
   8 - Download and install the latest .NET Core SDK for your platform https://www.microsoft.com/net/core#windowsvs2015 (archive for SDK 1.0.0-preview2-003121 located by: https://github.com/dotnet/core/blob/master/release-notes/download-archive.md)
   9 - Ensure that you have thrift.exe which supports netstd lib and it added to PATH
  10 - Go to current folder
  11 - Run **build.sh** or **build.cmd** from the root of cloned repository
  12 - Check tests in **src/Tests** folder
  13 - Continue with /tutorials/netstd
  14
  15 # How to run
  16
  17 Notes: dotnet run supports passing arguments to app after -- symbols (https://docs.microsoft.com/en-us/dotnet/articles/core/tools/dotnet-run) - example: **dotnet run -- -h** will show help for app
  18
  19 - build
  20 - go to folder (Client/Server)
  21 - run with specifying of correct parameters **dotnet run -tr:tcp -pr:multiplexed**, **dotnet run -help** (later, after migration to csproj and latest SDK will be possibility to use more usable form **dotnet run -- arguments**)
  22
  23 #Notes
  24 - Possible adding additional platforms after stabilization of .NET Core (runtimes, platforms (Red Hat Linux, OpenSuse, etc.)
  25
  26 #Known issues
  27 - In trace logging mode you can see some not important internal exceptions
  28
  29 # Running of samples
  30 Please install Thrift C# .NET Core library or copy sources and build them to correcly build and run samples
  31
  32 # NetCore Server
  33
  34 Usage:
  35
  36     Server.exe -h
  37         will diplay help information
  38
  39     Server.exe -tr:<transport> -pr:<protocol>
  40         will run server with specified arguments (tcp transport and binary protocol by default)
  41
  42 Options:
  43
  44     -tr (transport):
  45         tcp - (default) tcp transport will be used (host - ""localhost"", port - 9090)
  46         namedpipe - namedpipe transport will be used (pipe address - "".test"")
  47         http - http transport will be used (http address - ""localhost:9090"")
  48         tcptls - tcp transport with tls will be used (host - ""localhost"", port - 9090)
  49
  50     -bf (buffering):
  51         none - (default) no transport factory will be used
  52         buffered - buffered transport factory will be used
  53         framed - framed transport factory will be used (this must match the client)
  54
  55     -pr (protocol):
  56         binary - (default) binary protocol will be used
  57         compact - compact protocol will be used
  58         json - json protocol will be used
  59
  60 Sample:
  61
  62     Server.exe -tr:tcp
  63
  64 **Remarks**:
  65
  66     For TcpTls mode certificate's file ThriftTest.pfx should be in directory with binaries in case of command line usage (or at project level in case of debugging from IDE).
  67     Password for certificate - "ThriftTest".
  68
  69
  70
  71 # NetCore Client
  72
  73 Usage:
  74
  75     Client.exe -h
  76         will diplay help information
  77
  78     Client.exe -tr:<transport> -pr:<protocol> -mc:<numClients>
  79         will run client with specified arguments (tcp transport and binary protocol by default)
  80
  81 Options:
  82
  83     -tr (transport):
  84         tcp - (default) tcp transport will be used (host - ""localhost"", port - 9090)
  85         namedpipe - namedpipe transport will be used (pipe address - "".test"")
  86         http - http transport will be used (address - ""http://localhost:9090"")
  87         tcptls - tcp tls transport will be used (host - ""localhost"", port - 9090)
  88
  89     -bf (buffering):
  90         none - (default) no transport factory will be used
  91         buffered - buffered transport factory will be used
  92         framed - framed transport factory will be used (this must match the client)
  93
  94     -pr (protocol):
  95         binary - (default) binary protocol will be used
  96         compact - compact protocol will be used
  97         json - json protocol will be used
  98
  99     -mc (multiple clients):
 100         <numClients> - number of multiple clients to connect to server (max 100, default 1)
 101
 102 Sample:
 103
 104     Client.exe -tr:tcp -pr:binary -mc:10
 105
 106 Remarks:
 107
 108     For TcpTls mode certificate's file ThriftTest.pfx should be in directory
 109         with binaries in case of command line usage (or at project level in case of debugging from IDE).
 110     Password for certificate - "ThriftTest".
 111
 112 # How to test communication between NetCore and Python
 113
 114 * Generate code with the latest **thrift.exe** util
 115 * Ensure that **thrift.exe** util generated folder **gen-py** with generated code for Python
 116 * Create **client.py** and **server.py** from the code examples below and save them to the folder with previosly generated folder **gen-py**
 117 * Run netstd samples (client and server) and python samples (client and server)
 118
 119 Remarks:
 120
 121 Samples of client and server code below use correct methods (operations)
 122 and fields (properties) according to generated contracts from *.thrift files
 123
 124 At Windows 10 add record **127.0.0.1 testserver** to **C:\Windows\System32\drivers\etc\hosts** file
 125 for correct work of python server
 126
 127
 128 **Python Client:**
 129
 130 ```python
 131 import sys
 132 import glob
 133 sys.path.append('gen-py')
 134
 135 from tutorial import Calculator
 136 from tutorial.ttypes import InvalidOperation, Operation, Work
 137
 138 from thrift import Thrift
 139 from thrift.transport import TSocket
 140 from thrift.transport import TTransport
 141 from thrift.protocol import TBinaryProtocol
 142
 143
 144 def main():
 145     # Make socket
 146     transport = TSocket.TSocket('127.0.0.1', 9090)
 147
 148     # Buffering is critical. Raw sockets are very slow
 149     transport = TTransport.TBufferedTransport(transport)
 150
 151     # Wrap in a protocol
 152     protocol = TBinaryProtocol.TBinaryProtocol(transport)
 153
 154     # Create a client to use the protocol encoder
 155     client = Calculator.Client(protocol)
 156
 157     # Connect!
 158     transport.open()
 159
 160     client.Ping()
 161     print('ping()')
 162
 163     sum = client.Add(1, 1)
 164     print(('1+1=%d' % (sum)))
 165
 166     work = Work()
 167
 168     work.Op = Operation.Divide
 169     work.Num1 = 1
 170     work.Num2 = 0
 171
 172     try:
 173         quotient = client.Calculate(1, work)
 174         print('Whoa? You know how to divide by zero?')
 175         print('FYI the answer is %d' % quotient)
 176     except InvalidOperation as e:
 177         print(('InvalidOperation: %r' % e))
 178
 179     work.Op = Operation.Substract
 180     work.Num1 = 15
 181     work.Num2 = 10
 182
 183     diff = client.Calculate(1, work)
 184     print(('15-10=%d' % (diff)))
 185
 186     log = client.GetStruct(1)
 187     print(('Check log: %s' % (log.Value)))
 188
 189     client.Zip()
 190     print('zip()')
 191
 192     # Close!
 193     transport.close()
 194
 195 if __name__ == '__main__':
 196   try:
 197     main()
 198   except Thrift.TException as tx:
 199     print('%s' % tx.message)
 200 ```
 201
 202
 203 **Python Server:**
 204
 205
 206 ```python
 207 import glob
 208 import sys
 209 sys.path.append('gen-py')
 210
 211 from tutorial import Calculator
 212 from tutorial.ttypes import InvalidOperation, Operation
 213
 214 from shared.ttypes import SharedStruct
 215
 216 from thrift.transport import TSocket
 217 from thrift.transport import TTransport
 218 from thrift.protocol import TBinaryProtocol
 219 from thrift.server import TServer
 220
 221
 222 class CalculatorHandler:
 223     def __init__(self):
 224         self.log = {}
 225
 226     def Ping(self):
 227         print('ping()')
 228
 229     def Add(self, n1, n2):
 230         print('add(%d,%d)' % (n1, n2))
 231         return n1 + n2
 232
 233     def Calculate(self, logid, work):
 234         print('calculate(%d, %r)' % (logid, work))
 235
 236         if work.Op == Operation.Add:
 237             val = work.Num1 + work.Num2
 238         elif work.Op == Operation.Substract:
 239             val = work.Num1 - work.Num2
 240         elif work.Op == Operation.Multiply:
 241             val = work.Num1 * work.Num2
 242         elif work.Op == Operation.Divide:
 243             if work.Num2 == 0:
 244                 x = InvalidOperation()
 245                 x.WhatOp = work.Op
 246                 x.Why = 'Cannot divide by 0'
 247                 raise x
 248             val = work.Num1 / work.Num2
 249         else:
 250             x = InvalidOperation()
 251             x.WhatOp = work.Op
 252             x.Why = 'Invalid operation'
 253             raise x
 254
 255         log = SharedStruct()
 256         log.Key = logid
 257         log.Value = '%d' % (val)
 258         self.log[logid] = log
 259
 260         return val
 261
 262     def GetStruct(self, key):
 263         print('getStruct(%d)' % (key))
 264         return self.log[key]
 265
 266     def Zip(self):
 267         print('zip()')
 268
 269 if __name__ == '__main__':
 270     handler = CalculatorHandler()
 271     processor = Calculator.Processor(handler)
 272     transport = TSocket.TServerSocket(host="testserver", port=9090)
 273     tfactory = TTransport.TBufferedTransportFactory()
 274     pfactory = TBinaryProtocol.TBinaryProtocolFactory()
 275
 276     server = TServer.TSimpleServer(processor, transport, tfactory, pfactory)
 277     print('Starting the server...')
 278     server.serve()
 279     print('done.')
 280
 281     # You could do one of these for a multithreaded server
 282     # server = TServer.TThreadedServer(processor, transport, tfactory, pfactory)
 283     # server = TServer.TThreadPoolServer(processor, transport, tfactory, pfactory)
 284 ```