Re: [nbs] Scenarios (Was: Re: A suggestion for an "on-demand API".

[Javier Ubillos <[e-mail]>]

I've attempted to define some scenarios (two so far) test some API ideas
against.

Feel free to suggest and test new/more scenarios/cases.

Thank you Sowmini for the help and comments!

We're still trying to define an abstract API, please overlook if I slip
into C'ish syntax :)

I'm trying to find find an appropriate format for this... It's turning
out to be a pretty verbose e-mail.

* In both cases, we are assuming that there are a set of defaults
  (given by ALLOC_SOCKET() ?). E.g. unless other is noted, we're
  assuming FQDNs. 
  E.g."ACCEPT_FROM()" should be able to handle non-name-based-socket
  incoming messages. Either by accepting anything, or by using IPs
  instead of names.

* State on either side is stored and managed by the "CONNECTION" type.
  E.g. name->locator binding lifetime (as mentioned by Brian Carpenter
  previously)

* A CONNECTION type is a session-handle.

+----------------------------------------------------------------------+
| * One to one                                                         |
| * Bi-directional (e.g. TCP)                                          |
| * Bi-lateral support (Name-based sockets on both ends)               |
| * Requiring authentication of name->locator binding                  |
+----------------------------------------------------------------------+
|
|    -- Initiator:
|        CONNECTION *my_conn = ALLOC_SOCKET();
|
|        /* LOCAL_NAME() binds a local name. Unless some name-type is
|           chosen it defaults to FQDN */
|        LOCAL_NAME( my_conn, "initiator.name" ); 
|
|        DESTINATION_NAME( my_conn, "recipient.name" ); 
|        TRANSPORT( my_conn, TCP );
|        SERVICE( my_conn, HTTP ); // equivalent to htons(80)
|
|        /* In the TCP case "CONNECT()" performs a 3Way handshake 
|           Returns some error on failure.*/
|        if( 0 > CONNECT( my_conn ) ) return ERROR;
|        // Wait? Blocking or non blocking? Not yet defined.
|
|        // If the connection failed return an error.
|        if( ! IS_CONNECTED( my_conn ) ) return ERROR;
|       
|        // Let's send a greeting.
|       char* msg = "Hello remote node!";
|       SEND( my_conn, msg, strlen(msg) );
|
|   -- Recipient:
|       // Lets start listening for HTTP traffic over TCP.
|       CONNECTION *my_conn = ALLOC_SOCKET();
|       LOCAL_NAME( my_conn, "recipient.name" );
|       TRANSPORT_TCP( TCP | SCTP ); // Either protocol will be fine
|       SERVICE( my_conn, HTTP);
|
|       /* Accept from could either be null = accept from anyone or
|          one or more names which will be accepted. Unless some
|          name-type is chosen and some specific auth-method is picked
|          the check will consist of resolving the name in DNS and
|          checking if one or more of the locators matches the result
|          from DNS */
|       ACCEPT_FROM( my_conn, "initiator.name" ); 
|       /* Lets assume that this call is blocking. In the future, it
|          would be nice with being able to choose between two execution
|          paths, one for succeeded auths, one for one failed (e.g. for
|          non-upgraded hosts).  */
|
|       char *recv_buff[1024];
|       int read_chars = 0;
|       memset( recv_buff, 0, sizeof(recv_buff) );
|     
|       read_chars = READ( my_conn, recv_buff, sizeof(recv_buff) );
|
|       if( 0 < read_chars) printf("Recieved: %s\n", recv_buff);
|
+----------------------------------------------------------------------+

                                       
+----------------------------------------------------------------------+
| * One to one                                                         |
| * Uni-directional (e.g. UDP)                                         |
| * Uni-lateral support                                                |
| * Requiring authentication of name->locator binding                  |
+----------------------------------------------------------------------+
|
|    -- Initiator:
|        CONNECTION *my_conn = ALLOC_SOCKET();
|
|        /* LOCAL_NAME() binds a local name. Unless some name-type is
|           chosen it defaults to FQDN */
|        LOCAL_NAME( my_conn, "initiator.name" ); 
|        DESTINATION_NAME( my_conn, "recipient.name" ); 
|        TRANSPORT( my_conn, UDP );
|
|        // equivalent to htons(12333), my imaginary service :)
|        SERVICE( my_conn, MY_VIDEO ); 
|
|        /* In the UDP case "CONNECT()" just checks that we have all the
|           needed info to be able to send a packet. CONNECT() returns 
|           some sensible error if my_conn is incomplete */
|        if( 0 > CONNECT( my_conn ) ) return ERROR;
| 
|        // Let's send a greeting.
|        SEND( my_conn, "Hello remote node!" );
|
|    -- Recipient:
|        // Lets start listening for the service MY_VIDEO over UDP.
|        CONNECTION *my_conn = ALLOC_SOCKET();
|        LOCAL_NAME( my_conn, "recipient.name" );
|        TRANSPORT( UDP );
|        SERVICE( my_conn, MY_VIDEO);
|
|       /* Accept from could either be null = accept from anyone or
|          one or more names which will be accepted. Unless some
|          name-type is chosen and some specific auth-method is picked
|          the check will consist of resolving the name in DNS and
|          checking if one or more of the locators matches the result
|          from DNS */
|       ACCEPT_FROM( my_conn, "initiator.name" ); 
|       /* Lets assume that this call is blocking. In the future, it
|          would be nice with being able to choose between two execution
|          paths, one for suceeded auths, one for one failed (e.g. for
|          non-upgraded hosts). */
|
|        char *recv_buff[1024];
|        int read_chars = 0;
|        memset( recv_buff, 0, sizeof(recv_buff) );
|     
|        read_chars = READ( my_conn, recv_buff, sizeof(recv_buff) );
|
|        if( 0 < read_chars) printf("Recieved: %s\n", recv_buff);
|
+----------------------------------------------------------------------+   

// Javier