p2prc-0.1.0.0: P2PRC haskell library

Copyright | Copyright (C) 2024-2024 Jose Fernandes
License | GNU GPL, version 2 or above
Maintainer | Jose Fernandes <jf94.uk@gmail.com>
Stability | beta
Portability | portable
Safe Haskell | Safe-Inferred
Language | GHC2021

P2PRC

Contents

- Functions
- Data Types
  - Interface data types
  - Primitive data types
  - Type Synonyms

Description

This library provides an interface to the P2Prc runtime.

This Module intends to export the main functions and data type definitions necessary to get started with the P2PRC api.

A minimal application will require the import of `runP2PRC` function that accepts a `MapPortRequest` value that exposes a specific port number and associates it with a domain name in the internet.

This is a small template to get quickly get started with this interface. We assume the user has already an application listening on the tcp socket "8080".

    module Main where

    import P2PRC
      ( runP2PRC
      , MapPortRequest(MkMapPortRequest)
      )

    main :: IO ()
    main =
      runP2PRC
        ( MkMapPortRequest 8080 "jose.akilan.io"
        )

Synopsis

- runP2PRC :: MapPortRequest -> IO ()
- p2prcAPI :: P2PRCapi
- data P2PRCapi = MkP2PRCapi {
  - startServer :: IOEitherError ProcessHandle
  - execInitConfig :: IOEitherError P2prcConfig
  - execListServers :: IOEitherError IPAddressTable
  - execMapPort :: MapPortRequest -> IOEitherError MapPortResponse
  }
- newtype P2prcConfig = MkP2prConfig {
  - machineName :: String
  }
- data MapPortRequest = MkMapPortRequest Int String
- newtype MapPortResponse = MkMapPortResponse String
- newtype IPAddressTable = MkIPAddressTable [ServerInfo]
- data ServerInfo = MkServerInfo {
  - name :: Text
  - ip :: IPAddress
  - latency :: Int
  - download :: Int
  - upload :: Int
  - serverPort :: Int
  - bareMetalSSHPort :: Maybe Int
  - nat :: Bool
  - escapeImplementation :: Maybe Text
  - customInformation :: Maybe Text
  }
- data IPAddress
  - = MkIPv4 String
  - | MkIPv6 String
- data Error
  - = MkCLISystemError Int String String
  - | MkErrorSpawningProcess String
  - | MkUnknownError String
- type IOEitherError a = IO (Either Error a)

# Functions

These are the available functions available to interact with the P2Prc environment, at a lower level of abstraction. It is intended this way to give freedom to the developer to implement their own orchestration strategies.

runP2PRC #

Arguments

:: MapPortRequest | TCP Port Request
-> IO () |

This function starts and bootstraps the P2PRC runtime that associates the a specific host's machine port to a DNS address to expose a certain application to the P2PRC network. You will only need to also import the `MkMapPortRequest` data constructor to represent the this port request.

#### Example

Expand

This example demonstrates how it can be ran on the IO context:

     example :: IO ()
     example = do
       runP2PRC
         ( MkMapPortRequest 8080 "jose.akilan.io"
         )

p2prcAPI :: P2PRCapi #

Warning: This function is currently unstable because the configuration reading is dependent on the following issue: https://github.com/Akilan1999/p2p-rendering-computation/issues/120

This function intiates a pure P2PRC runtime state and builds up a `P2PRCapi` API instance. It allows a developer to create computing orchestration algorithms using the API primitives.

#### Example

Expand

The following example show how this function can be used to expose the runtime functionalities:

    module Main where

    import P2PRC
      ( p2prcAPI
      , P2PRCapi(..)
      )

    main :: IO ()
    main =

      print "Hello P2PRC"

      -- your code logic goes here

      where

      MkP2PRCapi
        { startServer=startServer
        , execMapPort=execMapPort
        , execListServers=execListServers
        , execInitConfig=execInitConfig
        } = p2prcAPI

# Data Types

This section describes and explains the library's type system, more specifically, the interfaces and primitive types.

## Interface data types

This section gives an overview on the runtime and host machine interfaces.

data P2PRCapi #

Lower level P2PRC Haskell api that exposes basic functionality necessary to joint the network.

Constructors

MkP2PRCapi |
Fields startServer :: IOEitherError ProcessHandle Start server execInitConfig :: IOEitherError P2prcConfig Instantiate server configuration execListServers :: IOEitherError IPAddressTable List servers in network execMapPort :: MapPortRequest -> IOEitherError MapPortResponse Exposes and associates a local TCP port with a remote DNS address

newtype P2prcConfig #

Warning: This type is unstable at the moment due to the P2PRC's library error handling bug. For more information visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114#issuecomment-2474737015

This represents the server configuration that defines its attributes and behaviours in the network, as well as, the location of the runtime persistence artifacts.

Constructors

MkP2prConfig |
Fields machineName :: String Machine Name

#### Instances

Instances details

FromJSON P2prcConfig # |
Instance details Defined in JSON Methods parseJSON :: Value -> Parser P2prcConfig # parseJSONList :: Value -> Parser [P2prcConfig] # omittedField :: Maybe P2prcConfig #
Show P2prcConfig # |
Instance details Defined in JSON Methods showsPrec :: Int -> P2prcConfig -> ShowS # show :: P2prcConfig -> String # showList :: [P2prcConfig] -> ShowS #

data MapPortRequest #

This defines the request required to create an association between a TCP socket port and a DNS server in the network. If successful, it makes a resource available in the network.

Constructors

MkMapPortRequest | P2PRC's port allocation request value
Fields Int TCP socket number String Network domain name

newtype MapPortResponse #

Warning: This newtype is unstable at the moment due to the P2PRC's library error handling bug. For more information visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114#issuecomment-2474737015

This represents P2PRC's response to the TCP port and DNS address allocation. This value will confirm the successful allocation and return information about it.

Constructors

MkMapPortResponse | Allocation information value
Fields String Column separated Host's IP address and Port String

#### Instances

Instances details

FromJSON MapPortResponse # |
Instance details Defined in JSON Methods parseJSON :: Value -> Parser MapPortResponse # parseJSONList :: Value -> Parser [MapPortResponse] # omittedField :: Maybe MapPortResponse #
Show MapPortResponse # |
Instance details Defined in JSON Methods showsPrec :: Int -> MapPortResponse -> ShowS # show :: MapPortResponse -> String # showList :: [MapPortResponse] -> ShowS #

## Primitive data types

These types represent the core data that is communicated between requests and the runtime.

newtype IPAddressTable #

Warning: This newtype is highly unstable due to undergoing work on improving P2PRC's server api. For more information, visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114

This is a wrapper value that parses a json key value from the list of ip addresses in the network.

Constructors

MkIPAddressTable | Wrapping constructor
Fields [ServerInfo] List current network servers

#### Instances

Instances details

FromJSON IPAddressTable # |
Instance details Defined in JSON Methods parseJSON :: Value -> Parser IPAddressTable # parseJSONList :: Value -> Parser [IPAddressTable] # omittedField :: Maybe IPAddressTable #
Show IPAddressTable # |
Instance details Defined in JSON Methods showsPrec :: Int -> IPAddressTable -> ShowS # show :: IPAddressTable -> String # showList :: [IPAddressTable] -> ShowS #

data ServerInfo #

Warning: This type is highly unstable due to undergoing work on improving P2PRC's server api. For more information, visit: https://github.com/Akilan1999/p2p-rendering-computation/issues/114

This is a record that keeps track of the current state of every node in the network. It is crucial information required for orchestration strategies.

Constructors

MkServerInfo |
Fields name :: Text Machine name ip :: IPAddress Machine IP address latency :: Int Response latency download :: Int Download speed upload :: Int Upload speed serverPort :: Int Server port number bareMetalSSHPort :: Maybe Int SSH machine port number nat :: Bool Checking if node is behind a NAT escapeImplementation :: Maybe Text Type of NAT trasversal technique customInformation :: Maybe Text Custom String information

#### Instances

Instances details

FromJSON ServerInfo # |
Instance details Defined in JSON Methods parseJSON :: Value -> Parser ServerInfo # parseJSONList :: Value -> Parser [ServerInfo] # omittedField :: Maybe ServerInfo #
Show ServerInfo # |
Instance details Defined in JSON Methods showsPrec :: Int -> ServerInfo -> ShowS # show :: ServerInfo -> String # showList :: [ServerInfo] -> ShowS #

data IPAddress #

This is a simple representation of the IP address of nodes in the network.

Constructors

MkIPv4 String | IP version 4 address
MkIPv6 String | IP version 6 address

#### Instances

Instances details

Show IPAddress # |
Instance details Defined in JSON Methods showsPrec :: Int -> IPAddress -> ShowS # show :: IPAddress -> String # showList :: [IPAddress] -> ShowS #

data Error #

Haskell-side Error value. This type is designed to parse and track System and P2PRC's error signals in a safe and effective manner.

It does have an `MkUnknownError` value which is meant to be warn about new kinds of error not yet accounted in this client. Github issues and pull requests are very welcome to improve error handling by parsing more types of errors.

Constructors

MkCLISystemError | This is a CLI System Error
Fields Int System error code String Command name executed String Error output
MkErrorSpawningProcess | Spawing process error
Fields String Spawning executable name
MkUnknownError | This is an unparsed P2PRC's error
Fields String Unparsed error message

#### Instances

Instances details

Show Error # |
Instance details Defined in Error Methods showsPrec :: Int -> Error -> ShowS # show :: Error -> String # showList :: [Error] -> ShowS #

## Type Synonyms

This section is reserved to some useful type synonyms that add significant ergonomics.

type IOEitherError a = IO (Either Error a) #

Type synonym for an IO action with either returns an Error or a parsed value