From 09b3260caf59629bcc4dee6499c53ca64976a913 Mon Sep 17 00:00:00 2001 From: pojntfx Date: Thu, 21 Dec 2023 15:56:28 +0000 Subject: [PATCH] deploy: 7b2a799baeabcaeaafabcb800b7bcf411eb91808 --- functions/linkWebSocket.html | 10 +-- index.html | 110 +++++++++++++++---------------- modules.html | 8 +-- variables/ErrorCallTimedOut.html | 10 +-- 4 files changed, 69 insertions(+), 69 deletions(-) diff --git a/functions/linkWebSocket.html b/functions/linkWebSocket.html index 10eb643..84ad3b5 100644 --- a/functions/linkWebSocket.html +++ b/functions/linkWebSocket.html @@ -1,4 +1,4 @@ -linkWebSocket | @pojntfx/dudirekta
+linkWebSocket | @pojntfx/ltsrpc
  • Preparing search index...
    • -
  • The search index is not available
@pojntfx/dudirekta
+
  • The search index is not available
    • @pojntfx/ltsrpc

    Function linkWebSocket

    @@ -99,7 +99,7 @@
    text: TReturns any

    Returns R

    +
  • Defined in registry.ts:25
    • @@ -119,7 +119,7 @@

    Theme

    @@ -6,37 +6,37 @@
    @pojntfx/dudirekta +
  • The search index is not available
    • @pojntfx/ltsrpc
    -

    @pojntfx/dudirekta

    +

    @pojntfx/ltsrpc

    - -

    dudirekta

    +     +

    ltsrpc

    Logo

    Language-, transport- and serialization-agnostic RPC framework with remote closure support that allows exposing and calling functions on both clients and servers.

    -

    hydrun CI +

    hydrun CI Go Version -Go Reference -npm CI -npm: @pojntfx/dudirekta -TypeScript docs -Matrix

    +Go Reference +npm CI +npm: @pojntfx/ltsrpc +TypeScript docs +Matrix

    Overview

     -

    dudirekta is a novel RPC framework with a unique feature: It allows exposing functions on both the client and server!

    +

    ltsrpc is a novel RPC framework with a unique feature: It allows exposing functions on both the client and server!

    It enables you to ...

      -
    • Call remote functions transparently: dudirekta makes use of reflection, so you can call functions as though they were local without defining your own protocol or generating code
      • -
    • Call functions on the client from the server: Unlike most RPC frameworks, dudirekta allows for functions to be exposed on both the server and the client, enabling its use in new usecases such as doing bidirectional data transfer without subscriptions or pushing information before the client requests it
      • -
    • Implement RPCs on any transport layer: By being able to work with any io.ReadWriteCloser such as TCP, WebSocket or WebRTC with the Stream-Oriented API, or any message-based transport such as Redis or NATS with the Message-Oriented API, you can use dudirekta to build services that run in almost any environment, including the browser!
      • -
    • Use an encoding/decoding layer of your choice: Instead of depending on Protobuf or another fixed format for serialization, dudirekta can work with every serialization framework that implements the basic Marshal/Unmarshal interface, such as JSON or CBOR.
      • -
    • Pass closures and callbacks to RPCs: Thanks to its bidirectional capabilities, dudirekta can handle closures and callbacks transparently, just like with local function calls!
      • +
    • Call remote functions transparently: ltsrpc makes use of reflection, so you can call functions as though they were local without defining your own protocol or generating code
      • +
    • Call functions on the client from the server: Unlike most RPC frameworks, ltsrpc allows for functions to be exposed on both the server and the client, enabling its use in new usecases such as doing bidirectional data transfer without subscriptions or pushing information before the client requests it
      • +
    • Implement RPCs on any transport layer: By being able to work with any io.ReadWriteCloser such as TCP, WebSocket or WebRTC with the Stream-Oriented API, or any message-based transport such as Redis or NATS with the Message-Oriented API, you can use ltsrpc to build services that run in almost any environment, including the browser!
      • +
    • Use an encoding/decoding layer of your choice: Instead of depending on Protobuf or another fixed format for serialization, ltsrpc can work with every serialization framework that implements the basic Marshal/Unmarshal interface, such as JSON or CBOR.
      • +
    • Pass closures and callbacks to RPCs: Thanks to its bidirectional capabilities, ltsrpc can handle closures and callbacks transparently, just like with local function calls!
    @@ -46,29 +46,29 @@

    Installation

    Library

     -

    You can add dudirekta to your Go project by running the following:

    -
    $ go get github.com/pojntfx/dudirekta/...@latest
+
    You can add ltsrpc to your Go project by running the following:
    
+
    $ go get github.com/pojntfx/ltsrpc/...@latest
 
    
 
    There is also a TypeScript version for browser and Node.js support (without transparent support for closures); you can install it like so:
    
-
    $ npm i -s @pojntfx/dudirekta
+
    $ npm i -s @pojntfx/ltsrpc
 
    
-
    This README's documentation only covers the Go version. For the TypeScript version, please check out Hydrapp, it uses dudirekta in its examples; you can also find the complete package reference here: TypeScript docs as well as example in ts/dudirekta-example-websocket-client.ts.
    
+
    This README's documentation only covers the Go version. For the TypeScript version, please check out Hydrapp, it uses ltsrpc in its examples; you can also find the complete package reference here: TypeScript docs as well as example in ts/ltsrpc-example-websocket-client.ts.
    
 
 
   
    durl Tool
    
     
-
    In addition to the library, the CLI tool durl is also available; durl is like cURL or gRPCurl, but for dudirekta: A command-line tool for interacting with dudirekta servers.
    
-
    Static binaries are available on GitHub releases.
    
+
    In addition to the library, the CLI tool durl is also available; durl is like cURL or gRPCurl, but for ltsrpc: A command-line tool for interacting with ltsrpc servers.
    
+
    Static binaries are available on GitHub releases.
    
 
    On Linux, you can install them like so:
    
-
    $ curl -L -o /tmp/durl "https://github.com/pojntfx/dudirekta/releases/latest/download/durl.linux-$(uname -m)"
    $ sudo install /tmp/durl /usr/local/bin
+
    $ curl -L -o /tmp/durl "https://github.com/pojntfx/ltsrpc/releases/latest/download/durl.linux-$(uname -m)"
    $ sudo install /tmp/durl /usr/local/bin
 
    
 
    On macOS, you can use the following:
    
-
    $ curl -L -o /tmp/durl "https://github.com/pojntfx/dudirekta/releases/latest/download/durl.darwin-$(uname -m)"
    $ sudo install /tmp/durl /usr/local/bin
+
    $ curl -L -o /tmp/durl "https://github.com/pojntfx/ltsrpc/releases/latest/download/durl.darwin-$(uname -m)"
    $ sudo install /tmp/durl /usr/local/bin
 
    
 
    On Windows, the following should work (using PowerShell as administrator):
    
-
    PS> Invoke-WebRequest https://github.com/pojntfx/dudirekta/releases/latest/download/durl.windows-x86_64.exe -OutFile \Windows\System32\durl.exe
+
    PS> Invoke-WebRequest https://github.com/pojntfx/ltsrpc/releases/latest/download/durl.windows-x86_64.exe -OutFile \Windows\System32\durl.exe
 
    
-
    You can find binaries for more operating systems and architectures on GitHub releases.
    
+
    You can find binaries for more operating systems and architectures on GitHub releases.
    
 
 
   
    Usage
    
@@ -80,7 +80,7 @@ 
    Usage
    
     
   
    1. Define Local Functions
    
     
-
    dudirekta uses reflection to create the glue code required to expose and call functions. Start by defining your server's exposed functions like so:
    
+
    ltsrpc uses reflection to create the glue code required to expose and call functions. Start by defining your server's exposed functions like so:
    
 
    // server.go

    type local struct {
        counter int64
    }

    func (s *local) Increment(ctx context.Context, delta int64) (int64, error) {
        log.Println("Incrementing counter by", delta, "for peer with ID", rpc.GetRemoteID(ctx))

        return atomic.AddInt64(&s.counter, delta), nil
    }
 
    
 
    In your client, define the exposed functions like so:
    
@@ -117,7 +117,7 @@ 
    3. Add Functions to a Registry
    
 
   
    4. Link the Registry to a Transport and Serializer
    
     
-
    Next, expose the functions by linking them to a transport. There are two available transport APIs; the Stream-Oriented API (which is useful for stream-like transports such as TCP, WebSockets, WebRTC or anything else that provides an io.ReadWriteCloser), and the Message-Oriented API (which is useful for transports that use messages, such as message brokers like Redis, UDP or other packet-based protocols). In this example, we'll use the stream-oriented API; for more information on using the m, meaning it can run in the browser!essage-oriented API, see Examples.
    
+
    Next, expose the functions by linking them to a transport. There are two available transport APIs; the Stream-Oriented API (which is useful for stream-like transports such as TCP, WebSockets, WebRTC or anything else that provides an io.ReadWriteCloser), and the Message-Oriented API (which is useful for transports that use messages, such as message brokers like Redis, UDP or other packet-based protocols). In this example, we'll use the stream-oriented API; for more information on using the m, meaning it can run in the browser!essage-oriented API, see Examples.
    
 
    Similarly so, as mentioned in Add Functions to a Registry, it is possible to use almost any serialization framework you want, as long as it can provide the necessary import interface. In this example, we'll be using the encoding/json package from the Go standard library, but in most cases, a more performant and compact framework such as CBOR is the better choice. See Benchmarks for usage examples with other serialization frameworks and a performance comparison.
    
 
    Start by creating a TCP listener in your main func (you could also use WebSockets, WebRTC or anything that provides a io.ReadWriteCloser) and passing in your serialization framework:
    
 
    // server.go

    lis, err := net.Listen("tcp", "localhost:1337")
    if err != nil {
        panic(err)
    }
    defer lis.Close()

    for {
        func() {
            conn, err := lis.Accept()
            if err != nil {
                return
            }

            go func() {
                defer func() {
                    _ = conn.Close()

                    if err := recover(); err != nil {
                        log.Printf("Client disconnected with error: %v", err)
                    }
                }()

                encoder := json.NewEncoder(conn)
                decoder := json.NewDecoder(conn)

                if err := registry.LinkStream(
                    func(v rpc.Message[json.RawMessage]) error {
                        return encoder.Encode(v)
                    },
                    func(v *rpc.Message[json.RawMessage]) error {
                        return decoder.Decode(v)
                    },

                    func(v any) (json.RawMessage, error) {
                        b, err := json.Marshal(v)
                        if err != nil {
                            return nil, err
                        }

                        return json.RawMessage(b), nil
                    },
                    func(data json.RawMessage, v any) error {
                        return json.Unmarshal([]byte(data), v)
                    },
                ); err != nil {
                        panic(err)
                    }
                }()
        }()
    }
@@ -142,7 +142,7 @@ 
    5. Call the Functions
    
 
   
    6. Using Closures and Callbacks
    
     
-
    Because dudirekta is bidirectional, it is possible to pass closures and callbacks as function arguments, just like you would locally. For example, on the server:
    
+
    Because ltsrpc is bidirectional, it is possible to pass closures and callbacks as function arguments, just like you would locally. For example, on the server:
    
 
    // server.go

    type local struct{}

    func (s *local) Iterate(
        ctx context.Context,
        length int,
        onIteration func(i int, b string) (string, error),
    ) (int, error) {
        for i := 0; i < length; i++ {
            rv, err := onIteration(i, "This is from the callee")
            if err != nil {
                return -1, err
            }

            log.Println("Closure returned:", rv)
        }

        return length, nil
    }

    type remote struct{}
 
    
 
    And the client:
    
@@ -151,7 +151,7 @@ 
    6. Using Closures and Callbacks
    
 
    When you call peer.Iterate, you can now pass in a closure:
    
 
    // client.go

    if err := registry.ForRemotes(func(remoteID string, remote remote) error {
        length, err := remote.Iterate(ctx, 5, func(i int, b string) (string, error) {
            log.Println("In iteration", i, b)

            return "This is from the caller", nil
        })
        if err != nil {
            return err
        }

        log.Println(length)
    }); err != nil {
        panic(err)
    }
 
    
-
    🚀 That's it! We can't wait to see what you're going to build with dudirekta.
    
+
    🚀 That's it! We can't wait to see what you're going to build with ltsrpc.
    
 
 
   
    Reference
    
@@ -160,45 +160,45 @@ 
    Reference
    
     
   
    Examples
    
     
-
    To make getting started with dudirekta easier, take a look at the following examples:
    
+
    To make getting started with ltsrpc easier, take a look at the following examples:
    
 
@@ -378,7 +378,7 @@ 
    Throughput
    
 
   
    Protocol
    
     
-
    The protocol used by dudirekta is simple and independent of transport and serialization layer; in the following examples, we'll use JSON.
    
+
    The protocol used by ltsrpc is simple and independent of transport and serialization layer; in the following examples, we'll use JSON.
    
 
    A function call to e.g. the Println function from above looks like this:
    
 
    {
      "request": {
        "call": "b3332cf0-4e50-4684-a909-05772e14595e",
        "function": "Println",
        "args": ["Hello, world!"]
      },
      "response": null
    }
 
    
@@ -387,12 +387,12 @@ 
    Protocol
    
 
    {
      "request": null,
      "response": {
        "call": "b3332cf0-4e50-4684-a909-05772e14595e",
        "value": null,
        "err": ""
      }
    }
 
    
 
    Here, response specifies that the message is a function return. call is the ID of the function call from above, value is the function's return value, and the last element is the error message; nil errors are represented by the empty string.
    
-
    Keep in mind that dudirekta is bidirectional, meaning that both the client and server can send and receive both types of messages to each other.
    
+
    Keep in mind that ltsrpc is bidirectional, meaning that both the client and server can send and receive both types of messages to each other.
    
 
 
   
    Reference
    
     
-
    $ durl --help
    Like cURL, but for dudirekta: Command-line tool for interacting with dudirekta servers

    Usage of durl:
        durl [flags] <(ws|wss|tcp|tls)://host:port/function> <[args...]>

    Example:
        durl wss://jarvis.fel.p8.lu/ToggleLights '["token", { "kitchen": true, "bathroom": false }]'

    Flags:
      -cert string
            TLS certificate
      -key string
            TLS key
      -listen
            Whether to connect to remotes by listening or dialing
      -timeout duration
            Time to wait for a response to a call (default 10s)
      -verbose
            Whether to enable verbose logging
      -verify
            Whether to verify TLS peer certificates (default true)
+
    $ durl --help
    Like cURL, but for ltsrpc: Command-line tool for interacting with ltsrpc servers

    Usage of durl:
        durl [flags] <(ws|wss|tcp|tls)://host:port/function> <[args...]>

    Example:
        durl wss://jarvis.fel.p8.lu/ToggleLights '["token", { "kitchen": true, "bathroom": false }]'

    Flags:
      -cert string
            TLS certificate
      -key string
            TLS key
      -listen
            Whether to connect to remotes by listening or dialing
      -timeout duration
            Time to wait for a response to a call (default 10s)
      -verbose
            Whether to enable verbose logging
      -verify
            Whether to verify TLS peer certificates (default true)
 
    
 
 
@@ -406,15 +406,15 @@ 
    Acknowledgements
    
   
    Contributing
    
     
 
    To contribute, please use the GitHub flow and follow our Code of Conduct.
    
-
    To build and start a development version of dudirekta locally, run the following:
    
-
    $ git clone https://github.com/pojntfx/dudirekta.git
    $ cd dudirekta
    $ go run ./cmd/dudirekta-example-tcp-server/ # Starts the TCP example server
    # In another terminal
    $ go run ./cmd/dudirekta-example-tcp-client/ # Starts the TCP example client
+
    To build and start a development version of ltsrpc locally, run the following:
    
+
    $ git clone https://github.com/pojntfx/ltsrpc.git
    $ cd ltsrpc
    $ go run ./cmd/ltsrpc-example-tcp-server/ # Starts the TCP example server
    # In another terminal
    $ go run ./cmd/ltsrpc-example-tcp-client/ # Starts the TCP example client
 
    
-
    Have any questions or need help? Chat with us on Matrix!
    
+
    Have any questions or need help? Chat with us on Matrix!
    
 
 
   
    License
    
     
-
    dudirekta (c) 2023 Felicitas Pojtinger and contributors
    
+
    ltsrpc (c) 2023 Felicitas Pojtinger and contributors
    
 
    SPDX-License-Identifier: Apache-2.0
    @@ -436,7 +436,7 @@

    Theme

    @@ -6,12 +6,12 @@
    • Preparing search index...
      • -
    • The search index is not available
    @pojntfx/dudirekta +
  • The search index is not available
    • @pojntfx/ltsrpc
    -

    @pojntfx/dudirekta

    +

    @pojntfx/ltsrpc

    Index

    @@ -42,7 +42,7 @@

    Theme

    @@ -6,18 +6,18 @@
    • Preparing search index...
      • -
    • The search index is not available
    @pojntfx/dudirekta +
  • The search index is not available
    • @pojntfx/ltsrpc

    Variable ErrorCallTimedOutConst

    ErrorCallTimedOut: "call timed out" = "call timed out"
    +
  • Defined in registry.ts:17
    • @@ -37,7 +37,7 @@

    Theme