zoossh

package module
v0.0.0-...-905a089 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2015 License: BSD-2-Clause Imports: 11 Imported by: 1

README

zoossh logo

Overview

zoossh is a parser written in Go for Tor-specific data formats. In case you are wondering, "zoossh" is the sound it makes when such documents are parsed! Though admittedly, the speed mostly comes from zoossh being implemented in a compiled language and not because the parsing code is particularly sophisticated.

At this point, zoossh should not be used in practice because the APIs are not yet stable.

Supported file formats

The following file formats are currently partially supported. For more information about file formats, have a look at CollecTor.

  • Server descriptors (@type server-descriptor 1.0)
  • Network status consensuses (@type network-status-consensus-3 1.0)

Examples

Here's how you can parse a network status document and iterate over all relay statuses:

consensus, _ := zoossh.ParseConsensusFile(fileName)
for _, status := range (*consensus).RouterStatuses {
    fmt.Println(status)
}

Similarly, here's how you can parse a file containing server descriptors:

descs, _ := zoossh.ParseDescriptorFile(fileName)
for _, desc := range descs {
    fmt.Println(desc)
}

Alternatives

Check out the Python library Stem or the Java library metrics-lib.

Contact

Contact: Philipp Winter phw@nymity.ch
OpenPGP fingerprint: B369 E7A2 18FE CEAD EB96 8C73 CF70 89E3 D7FD C0D0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Base64ToString 

func Base64ToString(encoded string) (string, error)

Decodes the given Base64-encoded string and returns the resulting string. If there are errors during decoding, an error string is returned.

func CheckAnnotation 

func CheckAnnotation(fd *os.File, expected map[Annotation]bool) error

Checks the type annotation in the given file. The Annotation struct determines what we want to see in the file. If we don't see the expected annotation, an error string is returned.

func DissectFile 

func DissectFile(fd *os.File, extractor StringExtractor, queue chan QueueUnit)

Dissects the given file into string chunks by using the given string extraction function. The resulting string chunks are then written to the given queue where the receiving end parses them.

func LazyParseRawDescriptor 

func LazyParseRawDescriptor(rawDescriptor string) (string, func() *RouterDescriptor, error)

LazyParseRawDescriptor lazily parses a raw router descriptor (in string format) and returns the descriptor's fingerprint, a function returning the descriptor, and an error if the descriptor could not be parsed. Parsing is delayed until the router descriptor is accessed.

func LazyParseRawStatus 

func LazyParseRawStatus(rawStatus string) (string, func() *RouterStatus, error)

LazyParseRawStatus parses a raw router status (in string format) and returns the router's fingerprint, a function which returns a RouterStatus, and an error if there were any during parsing. Parsing of the given string is delayed until the returned function is executed.

func LazyParseRawStatusMicro 

func LazyParseRawStatusMicro(rawStatus string) (string, func() *RouterStatus, error)

func ParseRawDescriptor 

func ParseRawDescriptor(rawDescriptor string) (string, func() *RouterDescriptor, error)

ParseRawDescriptor parses a raw router descriptor (in string format) and returns the descriptor's fingerprint, a function returning the descriptor, and an error if the descriptor could not be parsed. In contrast to LazyParseRawDescriptor, parsing is *not* delayed.

func ParseRawStatus 

func ParseRawStatus(rawStatus string) (string, func() *RouterStatus, error)

ParseRawStatus parses a raw router status (in string format) and returns the router's fingerprint, a function which returns a RouterStatus, and an error if there were any during parsing.

func ParseRawStatusMicro 

func ParseRawStatusMicro(rawStatus string) (string, func() *RouterStatus, error)

func StringToPort 

func StringToPort(portStr string) uint16

Convert the given port string to an unsigned 16-bit integer. If the conversion fails or the number cannot be represented in 16 bits, 0 is returned.

Types

type Annotation 

type Annotation struct {
	Type  string
	Major string
	Minor string
}

func GetAnnotation 

func GetAnnotation(fileName string) (*Annotation, error)

GetAnnotation obtains and returns the given file's annotation. If anything fails in the process, an error string is returned.

func (*Annotation) Equals 

func (a *Annotation) Equals(b *Annotation) bool

Equals checks whether the two given annotations have the same content.

func (*Annotation) String 

func (a *Annotation) String() string

type Consensus 

type Consensus struct {

	// A map from relay fingerprint to a function which returns the relay
	// status.
	RouterStatuses map[string]func() *RouterStatus
}

func LazilyParseConsensusFile 

func LazilyParseConsensusFile(fileName string) (*Consensus, error)

LazilyParseConsensusFile parses the given file and returns a network consensus if parsing was successful. If there were any errors, an error string is returned. Parsing of the router statuses is delayed until they are accessed using the Get method. As a result, this function is recommended as long as you won't access more than ~50% of all statuses.

func LazilyParseMicroConsensusFile 

func LazilyParseMicroConsensusFile(fileName string) (*Consensus, error)

func NewConsensus 

func NewConsensus() *Consensus

NewConsensus serves as a constructor and returns a pointer to a freshly allocated and empty Consensus.

func ParseConsensusFile 

func ParseConsensusFile(fileName string) (*Consensus, error)

ParseConsensusFile parses the given file and returns a network consensus if parsing was successful. If there were any errors, an error string is returned. In contrast to LazilyParseConsensusFile, parsing of router statuses is *not* delayed. As a result, this function is recommended as long as you will access most of all statuses.

func ParseMicroConsensusFile 

func ParseMicroConsensusFile(fileName string) (*Consensus, error)

func (*Consensus) Get 

func (c *Consensus) Get(fingerprint string) (*RouterStatus, bool)

Get returns the router status for the given fingerprint and a boolean value indicating if the status could be found in the consensus.

func (*Consensus) Intersect 

func (a *Consensus) Intersect(b *Consensus) *Consensus

Intersect determines the intersection between the given consensus b and consensus a. It returns a new consensus which is the intersection of both given consensuses.

func (*Consensus) Length 

func (c *Consensus) Length() int

Length returns the length of the consensus.

func (Consensus) PrintObjects 

func (c Consensus) PrintObjects()

PrintObjects implements the ObjectCollector interface.

func (*Consensus) Set 

func (c *Consensus) Set(fingerprint string, status *RouterStatus)

Set adds a new fingerprint mapping to a function returning the router status to the consensus.

func (*Consensus) Subtract 

func (a *Consensus) Subtract(b *Consensus) *Consensus

Subtract removes all routers which are part of the given consensus b from consensus a. It returns a new consensus which is the result of the subtraction.

type ExitPattern 

type ExitPattern struct {
	AddressSpec string
	PortSpec    string
}

An exitpattern as defined in dirspec.txt, Section 2.1.3.

type ObjectCollector 

type ObjectCollector interface {
	PrintObjects()
}

func ParseUnknownFile 

func ParseUnknownFile(fileName string) (ObjectCollector, error)

ParseUnknownFile attempts to parse a file whose content we don't know. We try to use the right parser by looking at the file's annotation. An ObjectCollector is returned if parsing was successful.

type QueueUnit 

type QueueUnit struct {
	Blurb string
	Err   error
}

type RouterDescriptor 

type RouterDescriptor struct {

	// The single fields of a "router" line.
	Nickname  string
	Address   net.IP
	ORPort    uint16
	SOCKSPort uint16
	DirPort   uint16

	// The single fields of a "bandwidth" line.  All bandwidth values are in
	// bytes per second.
	BandwidthAvg   uint64
	BandwidthBurst uint64
	BandwidthObs   uint64

	// The single fields of a "platform" line.
	OperatingSystem string
	TorVersion      string

	// The single fields of a "published" line.
	Published time.Time

	// The single fields of an "uptime" line.
	Uptime uint64

	// The single fields of a "fingerprint" line.
	Fingerprint string

	// The single fields of a "hibernating" line.
	Hibernating bool

	// The single fields of a "family" line.
	Family []string

	// The single fields of a "contact" line.
	Contact string

	// The "hidden-service-dir" line.
	HiddenServiceDir bool

	OnionKey     string
	NTorOnionKey string
	SigningKey   string

	Accept []*ExitPattern
	Reject []*ExitPattern
}

An (incomplete) router descriptor as defined in dirspec.txt, Section 2.1.1.

func (RouterDescriptor) String 

func (desc RouterDescriptor) String() string

Implement the Stringer interface for pretty printing.

type RouterDescriptors 

type RouterDescriptors struct {

	// A map from relay fingerprint to a function which returns the router
	// descriptor.
	RouterDescriptors map[string]func() *RouterDescriptor
}

func LazilyParseDescriptorFile 

func LazilyParseDescriptorFile(fileName string) (*RouterDescriptors, error)

LazilyParseDescriptorFile parses the given file and returns a pointer to RouterDescriptors containing the router descriptors. If there were any errors, an error string is returned. Note that parsing is done lazily which means that it is delayed until a given router descriptor is accessed. That pays off when you know that you will not parse most router descriptors.

func NewRouterDescriptors 

func NewRouterDescriptors() *RouterDescriptors

NewRouterDescriptors serves as a constructor and returns a pointer to a freshly allocated and empty RouterDescriptors struct.

func ParseDescriptorFile 

func ParseDescriptorFile(fileName string) (*RouterDescriptors, error)

ParseDescriptorFile parses the given file and returns a pointer to RouterDescriptors containing the router descriptors. If there were any errors, an error string is returned. Note that in contrast to LazilyParseDescriptorFile, parsing is *not* delayed. That pays off when you know that you will parse most router descriptors.

func (*RouterDescriptors) Get 

func (d *RouterDescriptors) Get(fingerprint string) (*RouterDescriptor, bool)

Get returns the router descriptor for the given fingerprint and a boolean value indicating if the descriptor could be found.

func (RouterDescriptors) PrintObjects 

func (desc RouterDescriptors) PrintObjects()

PrintObjects implements the ObjectCollector interface.

func (*RouterDescriptors) Set 

func (d *RouterDescriptors) Set(fingerprint string, descriptor *RouterDescriptor)

Set adds a new fingerprint mapping to a function returning the router descriptor.

type RouterFlags 

type RouterFlags struct {
	Authority bool
	BadExit   bool
	Exit      bool
	Fast      bool
	Guard     bool
	HSDir     bool
	Named     bool
	Stable    bool
	Running   bool
	Unnamed   bool
	Valid     bool
	V2Dir     bool
}

func (RouterFlags) String 

func (flags RouterFlags) String() string

Implement the Stringer interface for pretty printing.

type RouterStatus 

type RouterStatus struct {

	// The single fields of an "r" line.
	Nickname    string
	Fingerprint string
	Digest      string
	Publication time.Time
	Address     net.IP
	ORPort      uint16
	DirPort     uint16

	// The single fields of an "s" line.
	Flags RouterFlags

	// The single fields of a "v" line.
	TorVersion string

	// The single fields of a "w" line.
	Bandwidth  uint64
	Measured   uint64
	Unmeasured bool

	// The single fields of a "p" line.
	Accept   bool
	PortList string

	// The single fields of a "m" line.
	MicroDigest string
}

func (RouterStatus) String 

func (status RouterStatus) String() string

Implement the Stringer interface for pretty printing.

type StringExtractor 

type StringExtractor func(string) (string, bool, error)

Extracts a string unit from an archive file that can be readily thrown into the respective parser.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.