Copyright	Copyright (C) 2024-2024 Jose Fernandes
License	GNU GPL, version 2 or above
Maintainer	Jose Fernandes <[email protected]>
Stability	beta
Portability	portable
Safe Haskell	Safe-Inferred
Language	GHC2021

P2PRC

Contents

Functions
Data Types

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 ()
getP2prcAPI :: IOEitherError P2PRCapi
data P2PRCapi = MkP2PRCapi {
}
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
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"
     )

getP2prcAPI :: IOEitherError P2PRCapi #

Warning: This function is currently unstable since it assumes that the Haskell program is executed from the P2PRC "haskell" subfolder and the "p2prc" executable in the the root folder.

This function cleans the previous running state (ensuring a pure P2PRC runtime state) and builds up a conditional P2PRCapi instance.

Example

Expand

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

 example :: IOEitherError P2PRCapi
 example = do

   eitherP2prcAPI <- getP2prcAPI

   case eitherP2prcAPI of
     ( Right
       ( MkP2PRCapi
         { startServer     = startServer
         , execInitConfig  = execInitConfig
         , execListServers = execListServers
         , execMapPort     = execMapPort
         }
       )) -> do

       -- Your code logic

     errValue -> errValue

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