github.com/shyftnetwork/go-empyrean@v1.8.3-0.20191127201940-fbfca9338f04/swarm/pss/client/doc.go (about)

     1  // Copyright 2018 The go-ethereum Authors
     2  // This file is part of the go-ethereum library.
     3  //
     4  // The go-ethereum library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The go-ethereum library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  // simple abstraction for implementing pss functionality
    18  //
    19  // the pss client library aims to simplify usage of the p2p.protocols package over pss
    20  //
    21  // IO is performed using the ordinary p2p.MsgReadWriter interface, which transparently communicates with a pss node via RPC using websockets as transport layer, using methods in the PssAPI class in the swarm/pss package
    22  //
    23  //
    24  // Minimal-ish usage example (requires a running pss node with websocket RPC):
    25  //
    26  //
    27  //   import (
    28  //  	"context"
    29  //  	"fmt"
    30  //  	"os"
    31  //  	pss "github.com/ShyftNetwork/go-empyrean/swarm/pss/client"
    32  //  	"github.com/ShyftNetwork/go-empyrean/p2p/protocols"
    33  //  	"github.com/ShyftNetwork/go-empyrean/p2p"
    34  //  	"github.com/ShyftNetwork/go-empyrean/swarm/pot"
    35  //  	"github.com/ShyftNetwork/go-empyrean/swarm/log"
    36  //  )
    37  //
    38  //  type FooMsg struct {
    39  //  	Bar int
    40  //  }
    41  //
    42  //
    43  //  func fooHandler (msg interface{}) error {
    44  //  	foomsg, ok := msg.(*FooMsg)
    45  //  	if ok {
    46  //  		log.Debug("Yay, just got a message", "msg", foomsg)
    47  //  	}
    48  //  	return errors.New(fmt.Sprintf("Unknown message"))
    49  //  }
    50  //
    51  //  spec := &protocols.Spec{
    52  //  	Name: "foo",
    53  //  	Version: 1,
    54  //  	MaxMsgSize: 1024,
    55  //  	Messages: []interface{}{
    56  //  		FooMsg{},
    57  //  	},
    58  //  }
    59  //
    60  //  proto := &p2p.Protocol{
    61  //  	Name: spec.Name,
    62  //  	Version: spec.Version,
    63  //  	Length: uint64(len(spec.Messages)),
    64  //  	Run: func(p *p2p.Peer, rw p2p.MsgReadWriter) error {
    65  //  		pp := protocols.NewPeer(p, rw, spec)
    66  //  		return pp.Run(fooHandler)
    67  //  	},
    68  //  }
    69  //
    70  //  func implementation() {
    71  //      cfg := pss.NewClientConfig()
    72  //      psc := pss.NewClient(context.Background(), nil, cfg)
    73  //      err := psc.Start()
    74  //      if err != nil {
    75  //      	log.Crit("can't start pss client")
    76  //      	os.Exit(1)
    77  //      }
    78  //
    79  //	log.Debug("connected to pss node", "bzz addr", psc.BaseAddr)
    80  //
    81  //      err = psc.RunProtocol(proto)
    82  //      if err != nil {
    83  //      	log.Crit("can't start protocol on pss websocket")
    84  //      	os.Exit(1)
    85  //      }
    86  //
    87  //      addr := pot.RandomAddress() // should be a real address, of course
    88  //      psc.AddPssPeer(addr, spec)
    89  //
    90  //      // use the protocol for something
    91  //
    92  //      psc.Stop()
    93  //  }
    94  //
    95  // BUG(test): TestIncoming test times out due to deadlock issues in the swarm hive
    96  package client