SDK API discussion

[vsbogd]

I have created this issue to discuss the API which should be provided by SDK for client development.
Currently implemented approach is to generate client API stubs on the fly when new client instance is created (see Usage section of the README.md).

Example I have posted below has two items which I would like to discuss:

1. it contains some example of API which can be used to configure SingularityNet service interaction session
2. it demonstrates client implementation when client stubs are generated in advance, before developing a client code.

import snet
import snet.example_service as example_service

# Define identity, ethereum endpoint, IPFS endpoint, session cache strategy
identity = snet.PrivateKeyIdentity("path/to/private/key") 
eth = snet.KovanEth()
ipfs = snet.SnetIpfs()
cache = snet.FileSystemSessionCache("path/to/cache/folder")
session = snet.Session(identity=identity, eth=eth, ipfs=ipfs, cache=cache)

# Check AGI tokens balance and MultiPartyEscrow contract balance of session
# identity, and deposit tokens to the MultiPartyEscrow.
print("AGI tokens available:", session.balance())
session.deposit(1000)
print("AGI tokens available:", session.balance())

# Instantiate "Example Service" client and call the method.
# example_service.Calculator is generated as prerequisite step, for example
# user calls `snet sdk` command providing org_id and service_id to generate
# snet.example_service package with all necessary stubs. All logic related to
# opening channel, finding proper endpoint, switching between endpoints is
# embedded into service stub.
example_service = example_service.Calculator(session)
numbers = example_service.Numbers(a=7, b=6)
result = example_service.mul(numbers)
print("Calculation result:", result.value)
print("AGI tokens available:", session.balance())

Item 2 is not so important probably for interpreted languages like Python or JavaScript but it can be faster and may be simpler than generating stubs on the fly. BTW it is harder to reuse such stubs in snet-cli so it is a bit contradicts to issue #9.

[vsbogd]

I would like to welcome anyone to share your thoughts on both items.

[raamb]

@vsbogd the session concept sounds quite interesting.
Will it abstract out the channel completely? I.e. it will automatically create / fund / extend a channel as well as internally manage channels by service

If I were to extend your example to interact with two different services as shown below, is the session object expected to manage channels separately?

session.deposit(1000)

example_service = example_service.Calculator(session)
numbers = example_service.Numbers(a=7, b=6)
result = example_service.mul(numbers)
print("Calculation result:", result.value)
print("AGI tokens available:", session.balance())

cntk_image_service=cntk_image_service.Recognizer(session)
image = cntk_image_service.Input(img_path="/some_path/some_file.jpg")
result = cntk_image_service.flowers(image)
print("Response is ",result.top_5)
print("AGI tokens available:", session.balance())

[astroseger]

1. We need an abstraction for configuration. As a basis we could take snet-cli configuration and extend it, or probably we could define new SDK format from scratch. Of course it should be an abstract class, so user can provide config as they want (not necessary via config file).
2. We need to pass org_id and service_id somehow, or we need to hardcode it somewhere, because we need to find metadata for this service. ( As an alternative we could directly hardcode metadata, but in this case we will not support any updates to metadata.)
3. I'm not sure that we need the session. There is no real session here. There is only web3 client which might work well when we initialize it multiply times. It should be tested.
4. @raamb It is very straightforward to dynamically manage channels (create/fund/extend). But we need very very very carefully manage the obvious danger associated with it! We need to have the following parameters in configuration: is_allow_transaction, maximal_channel_expiration, maximal_channel_value, maximal_price_per_call, ...

For example statically compiled example of @vsbogd will look like this:
(I will write it without "session", but I'm not 100% sure that it is the best strategy)

import snet
import snet.example_service as example_service

# load configuration which contains: 
# - current ethereum identity
# - current network (with all information: rpc_endpoint, default_gas_price_strategy and optional contract_addresses)
# - ipfs endpoint
# (SDK specific) - caching strategy
# (SDK specific) - "is_allow_transaction" and others..

config = snet.config("/path/to/your/config")

# we need to pass <org_id> <service_id> here, or hardcode it in "snet.example_service"
example_service = example_service.Calculator(config, "<org_id>", "<service_id>")
# the rest is like in @vsbogd example
....

We might also want to support dynamically compiled calls:

import snet
import snet.call_stub_generator as call_stub_generator

config = snet.config("/path/to/your/config")

stub = call_stub_generator("snet", "example-service", "add")
# parameters could be a dictionary, I don't think that we need Request class here
params = {"a":1, "b":2}
rez = stub(params)

[ferrouswheel]

What will people use if they are testing their service and want to use the same code path, but making grpc requests without the extra SNet headers?

This is why I suggested matching the grpc API, unless we are planning to do major API work for every programming language and want to force people to learn our new API when the grpc API already exists.

The alternative is the dynamically compiled calls that Sergey has already implemented. It is perfect for ease of use when people are prototyping an integration with an SNet service. I'm not sure a halfway point between fully dynamic and fully grpc API is useful.

I don't understand how this will work:

import snet.example_service as example_service

Since the session is set up after the import, and the snet package will have no way to know what network, registry or org to use to find example_service.

Rereading the code example I see the mention of running a CLI command to generate the stub. This makes sense and will be required for any compiled language anyhow. However, there are then these questions:

• how do we check that the generated code is correct for the network/registry being used in the session?
• what if there are multiple orgs with the same service name that the sdk user wants to integrate with? (e.g. if they are comparing the accuracy of two similar services provided by different people)
• if we have most of the session information when the stub is generated (ipfs, network id), why not encode that in the generated code to avoid mismatches?
• How to we translate characters that are not allowed in module names like -?

If we do this anyway, I think we should namespace services from the rest of our sdk snet.service.ORG.SERVICE_NAME. Mixing it in with the root module could result in weird name collisions and possible security issues.

[ferrouswheel]

After thinking about this, I realise the session object could be configured in a way to remove all the SNet stuff and preserve the same code path when people are testing their service outside of SNet. Something like:

session = DirectSession(endpoint="127.0.0.1:8080")

which could then be passed to the stub creator.

The question about how much we should diverge from standard grpc/protobuf API still remains though.

[ferrouswheel]

If we use a Session object, I would prefer us not to go overboard with argument classes. It makes sense for identity, but there is no need to make ipfs and network setup an object, just make them string arguments to the session. If we want to have defaults that are easy to use instead of remembering endpoints, provide those as class or module constants: e.g.

session = Session(identity=..., ipfs=snet.DEFAULT_IPFS, network=snet.KOVAN)
# of course, if these are the default, then it just becomes:
session = Session(identity=...)

Or KovanSession(), MainnetSession() to make it clearer which environment is being used. These kind of extra class objects I'm okay with because it simplifies the API for the user rather than making them have to worry about composition of the configurations.

(Sorry for three comments in a row!)

[astroseger]

@ferrouswheel
There are more parameters which should be passed, and not only identity/network/ipfs...
Why not make an abstraction for config? Even if you want to stick to session abstraction...

config = snet.config("/path/to/your/config")

# or it might be like this:
# config2 = snet.static_config(identity=, ipfs=...,network, buch_of_other_parameteters=...)

session = session(config=config)

However here a session is actually a state of current configuration. I'm not sure that we need to initialize something in the session (it means that we might not need an abstraction for session, but of course we might keep it... )

[ferrouswheel]

I'm not fussed about session vs config. I'd prefer fewer things to set up, but I don't know enough to say whether a session is necessary...

Sorry, I didn't add all the parameters to try to keep it simple... everything that has a sensible default should use the sensible default. What are the bare minimum arguments required that we can't assume?

As far as I can tell it's network and identity.

Anyhow, I was primarily wanting us to avoid snet.KovanEth() and other objects for things that don't need be an object. Let people use strings unless there is a really really good reason to introduce a new class.

[raamb]

4. @raamb It is very straightforward to dynamically manage channels (create/fund/extend). But we need very very very carefully manage the obvious danger associated with it! We need to have the following parameters in configuration: is_allow_transaction, maximal_channel_expiration, maximal_channel_value, maximal_price_per_call, ...

Exactly, we need to be very careful. Even if we go with the session approach, I would prefer to have channels called out as an explicit entity. The channel concept is very important to call out even if we simplify it.

[astroseger]

After playing with current SDK and trying to merge it with functions from snet-cli I came the the following API:

I propose to have two types of clients:

• one which do not send blockchain transactions at all (BasicClient)
• one which automatically add funds and extend channel (AutoRefundingClient)

It should be noted that:

1. It is plain GRPC (exactly like in @vforvalerio87 SDK which was a basis for this code) with some syntactic sugar.
2. Here we automatically download and compile protobuf files (with dynamical caching for everything). But static location for protobuf files can be easily specified if needed.
3. I propose to discuss API first and after we will discuss the implementation (I do not insist on this implemented, we can adapt the current SDK without using functions from snet-cli, and then reuse it in snet-cli).
4. I haven't solve problem with possible attack from the server provider who change the price...

You should get this branch to run the following examples: https://github.com/astroseger/snet-cli/tree/new-sdk (new-sdk branch in my repo!).

Example for AutoFundingClient

from snet_cli.sdk import Session, BasicClient, AutoFundingClient
from snet_cli.config import Config

# we directly use snet-cli configuration
# another types of configuration can be easiliy implemented (for example hard-coded configuration)
session = Session(Config())

# we automatically open channel if needed
# each time we run out of funds we add 10 cogs
# each time we run out of "expiration" we add 20 days
client = AutoFundingClient(session, "snet", "example-service", "add", 10, "+20days")

for i in range(1000):
    request = client.request_class(a=20, b=i)
    rez = client.stub.add(request)
    print(rez)

Example with BasicClient (and two helper functions: reserve_funds and unspent_amount):

from snet_cli.sdk import Session, BasicClient, AutoFundingClient
from snet_cli.config import Config

session = Session(Config())

# we automatically open channel if needed!
# add 10 cogs to snet/example-service escrow
session.reserve_funds("snet", "example-service", 10, "+100days")
client = BasicClient(session, "snet", "example-service", "add")

for i in range(1000):
    unspent_amount = client.unspent_amount()
    if (unspent_amount < 1):
        session.reserve_funds("snet", "example-service", 10, "+100days")

    request = client.request_class(a=20, b=i)
    rez = client.stub.add(request)
    print(rez)

[ferrouswheel]

client = BasicClient(session, "snet", "example-service", "add")

We should not force the client to be dependent on the method called. When people start providing richer APIs (beyond a single request/response method) it will be annoying to create a new client for every method.

It is plain GRPC

Can you include an example of how you would use plain GRPC? Are all the request and response protobuf classes available via the client? What happens if their API names clash with client property names?

[astroseger]

@ferrouswheel
It is plain grpc, because:

• client.stub is proper grpc stub
• client.request_class is proper grpc request_class
• (if you need it) client.response_class is a proper grpc response class

Can you include an example of how you would use plain GRPC?

What exactly do you want?

If you want to test your service before registered it then I have the question to your: Do you want to do it with or without a daemon?

If you want to test your service without the daemon (so without any channels and payments), then you can directly use grpc. If you want I can add a class with the same syntactic sugar... Something like this:

# ATTENTION!!! this example will not work, it is not implemented yet
from snet_cli.sdk import TestClient

client = TestClient("/path/to/your/compiled/protobuf/files/", "add")

for i in range(1000):
    request = client.request_class(a=20, b=i)
    rez = client.stub.add(request)

If you want to test your service with a daemon (but without registered it in Registry). Then we have mechanism in snet-cli to initialize service directly from metadata (@raamb preventing me to remove this mechanism recently :) ). So you initialize your service and directly use BasicClient or AutoFundingClient. I want to underline that if your service is Registered in Registry then all initialization is done automatically on fly. Of course without registration we cannot do it on fly.

[ferrouswheel]

There is more complexity to grpc and protobuf messages than just request and response classes, and those will become far more obvious outside of python (in any staticly typed language). And as I said. I really think making clients dependent on the specific method is a bad idea. If you were creating an http request library, you wouldn't create a new client for every http url!

…

On Mon, 11 Mar 2019, 9:40 PM Sergey Rodionov, ***@***.***> wrote: @ferrouswheel <https://github.com/ferrouswheel> It is plain grpc, because: - client.stub is proper grpc stub - client.request_class is proper grpc request_class - (if you need it) client.response_class is a proper grpc response class Can you include an example of how you would use plain GRPC? What exactly do you want? If you want to test your service before registered it then I have the question to your: Do you want to do it with or without a daemon? If you want to test your service without the daemon (so without any channels and payments), then you can directly use grpc. If you want I can add a class with the same syntactic sugar... Something like this: # ATTENTION!!! this example will not work, it is not implemented yetfrom snet_cli.sdk import TestClient client = TestClient("/path/to/your/compiled/protobuf/files/", "add") for i in range(1000): request = client.request_class(a=20, b=i) rez = client.stub.add(request) If you want to test your service with a daemon (but without registered it in Registry). Then we have mechanism in snet-cli to initialize service directly from metadata ***@***.*** <https://github.com/raamb> preventing me to remove this mechanism recently :) ). So you initialize your service and directly use BasicClient or AutoFundingClient. I want to underline that if your service is Registered in Registry then all initialization is done automatically on fly. Of course without registration we cannot do it on fly. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#16 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAHWB1SZoWExFDKSEwPZice1ydf40ekNks5vVhaNgaJpZM4bilJ6> .

[chetankothari]

Extending the idea @astroseger proposed here about multiple clients, with and without auto funding.

Rather than having two different clients we could rather have one client and allow the user change the funding strategy and we could provide a default strategy which the user needs to explicitly connect to the client.

Something along these lines (extending @astroseger's example)

from snet_cli.sdk import Session, Client, DefaultFundingStrategy
from snet_cli.config import Config
    
# we directly use snet-cli configuration
# another types of configuration can be easiliy implemented (for example hard-coded configuration)
session = Session(Config())

# we automatically open channel if needed
# each time we run out of funds we add 10 cogs
# each time we run out of "expiration" we add 20 days
client = Client(session, DefaultFundingStrategy(), "snet", "example-service", "add", 10, "+20days")
    
for i in range(1000):
request = client.request_class(a=20, b=i)
rez = client.stub.add(request)
print(rez)

If the user wants to define her own funding strategy we could define a contract which a strategy needs to adhere to.

This then opens up possibilities for a lot of different strategies the user can define without changing the client.

If we think this is a good path to take then we could work towards refining this further.