# P2PRC

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