Transportation APIs

Command goat provides an implementation of a BitTorrent tracker, written in Go. goat can be built using Go 1.1+. It can be downloaded, built, and installed, simply by running: In addition, goat depends on a MySQL server for data storage. After creating a database and user for goat, its database schema may be imported from the SQL files located in 'res/'. goat will not run unless MySQL is installed, and a database and user are properly configured for its use. Optionally, goat can be built to use ql (https://github.com/cznic/ql) as its storage backend. This is done by supplying the 'ql' tag in the go get command: A blank ql database file is located under 'res/ql/goat.db', and will be copied to '~/.config/goat/goat.db' on UNIX systems. goat is now able to use ql as its storage backend, for those who do not wish to use an external, MySQL backend. goat is capable of listening for torrent traffic in three modes: HTTP, HTTPS, and UDP. HTTP/HTTPS are the recommended methods, and are required in order for goat to serve its API, and to allow use of private tracker passkeys. HTTP is considered the standard mode of operation for goat. HTTP allows gathering a great number of metrics, use of passkeys, use of a client whitelist, and access to goat's RESTful API, when configured. For most trackers, this will be the only listener which is necessary in order for goat to function properly. The HTTPS listener provides a method to encrypt traffic to the tracker, but must be used with caution. Unless the SSL certificate in use is signed by a proper certificate authority, it will distress most clients, and they may outright refuse to announce to it. If you are in possession of a certificate signed by a certificate authority, this mode may be more ideal, as it provides added security for your clients. The UDP listener is the most unusual method of the three, and should only be used for public trackers. The BitTorrent UDP tracker protocol specifies a very specific packet format, meaning that additional information or parameters cannot be packed into a UDP datagram in a standard way. The UDP tracker may be the fastest and least bandwidth-intensive, but as stated, should only be used for public trackers. A new feature goat added to goat in order to allow better interoperability with many languages is a RESTful API, which is served using the HTTP or HTTPS listeners. This API enables easy retrieval of tracker statistics, while allowing goat to run as a completely independent process. It should be noted that the API is only enabled when configured, and when a HTTP or HTTPS listener is enabled. Without a transport mechanism, the API will be inaccessible. The API features several modes of authentication, including HTTP Basic for login and HMAC-SHA1 other calls. Upon logging into the API using HTTP Basic with a username and password pair, an API public key and secret will be generated. The public key is used as the username for HTTP Basic authentication, and the secret key is used to calculate a HMAC-SHA1 signature for the password. As part of API signature generation, a random nonce value must be generated and added to the request. It is added to the password portion of the HTTP Basic request, and also to the string which is used to create the signature. Nonce values must be changed on every request, or the request will fail. The current pseudocode format of the HMAC-SHA1 signature is as follows: The proper format for a HTTP Basic request is as follows: When the public key, nonce, and API signature are sent via HTTP Basic, the server will verify the signature. Successful authentication will allow access to the API. This list contains all API calls currently recognized by goat. Each call must be authenticated using the aforementioned methods. Request an API public key and secret key for this user. The public key, user ID, and secret key are used to authenticate further API calls. The expire time indicates when this key is set to expire. Further API calls will extend the expiration time. Retrieve a list of all files tracked by goat. Some extended attributes are not added to reduce strain on database, and to provide a more general overview. Retrieve extended attributes about a specific file with matching ID. This provides counts for number of completions, seeders, leechers, and a list of fileUser relationships associated with a given file. Retrieve a variety of metrics about the current status of goat, including its PID, hostname, memory usage, number of HTTP/UDP hits, etc. Create a user with the specified username, password, and torrent limit. Reterieve a list of all users registered to goat, including their ID, torrent limit, and username. Retrieve information about a single user with matching ID, including their ID, torrent limit, and username. goat is configured using a JSON file, which will be created under '~/.config/goat/config.json' on UNIX systems. Here is an example configuration, describing the settings available to the user.

Package pulseaudio is a pure-Go (no libpulse) implementation of the PulseAudio native protocol. Rather than exposing the PulseAudio protocol directly this library attempts to hide the PulseAudio complexity behind a Go interface. Some of the things which are deliberately not exposed in the API are: → backwards compatibility for old PulseAudio servers → transport mechanism used for the connection (Unix sockets / memfd / shm) → encoding used in the pulseaudio-native protocol Querying and setting the volume. Listing audio outputs. Changing the default audio output. Notifications on config updates.

Package httpexpect helps with end-to-end HTTP and REST API testing. See example directory: There are two common ways to test API with httpexpect: The second approach works only if the server is a Go module and its handler can be imported in tests. Concrete behaviour is determined by Client implementation passed to Config struct. If you're using http.Client, set its Transport field (http.RoundTriper) to one of the following: Note that http handler can be usually obtained from http framework you're using. E.g., echo framework provides either http.Handler. You can also provide your own implementation of RequestFactory (creates http.Request), or Client (gets http.Request and returns http.Response). If you're starting server from tests, it's very handy to use net/http/httptest. Whenever values are checked for equality in httpexpect, they are converted to "canonical form": This is equivalent to subsequently json.Marshal() and json.Unmarshal() the value and currently is implemented so. When some check fails, failure is reported. If non-fatal failures are used (see Reporter interface), execution is continued and instance that was checked is marked as failed. If specific instance is marked as failed, all subsequent checks are ignored for this instance and for any child instances retrieved after failure. Example: If you want to be informed about every asserion made, successful or failed, you can use AssertionHandler interface. Default implementation of this interface ignores successful assertions and reports failed assertions using Formatter and Reporter objects. Custom AssertionHandler can handle all assertions (e.g. dump them in JSON format) and is free to use or not to use Formatter and Reporter in its sole discretion.

Package httpexpect helps with end-to-end HTTP and REST API testing. See example directory: There are two common ways to test API with httpexpect: The second approach works only if the server is a Go module and its handler can be imported in tests. Concrete behaviour is determined by Client implementation passed to Config struct. If you're using http.Client, set its Transport field (http.RoundTriper) to one of the following: Note that http handler can be usually obtained from http framework you're using. E.g., echo framework provides either http.Handler or fasthttp.RequestHandler. You can also provide your own implementation of RequestFactory (creates http.Request), or Client (gets http.Request and returns http.Response). If you're starting server from tests, it's very handy to use net/http/httptest. Whenever values are checked for equality in httpexpect, they are converted to "canonical form": This is equivalent to subsequently json.Marshal() and json.Unmarshal() the value and currently is implemented so. When some check fails, failure is reported. If non-fatal failures are used (see Reporter interface), execution is continued and instance that was checked is marked as failed. If specific instance is marked as failed, all subsequent checks are ignored for this instance and for any child instances retrieved after failure. Example:

muxado implements a general purpose stream-multiplexing protocol. muxado allows clients applications to multiplex any io.ReadWriteCloser (like a net.Conn) into multiple, independent full-duplex streams. muxado is a useful protocol for any two communicating processes. It is an excellent base protocol for implementing lightweight RPC. It eliminates the need for custom async/pipeling code from your peers in order to support multiple simultaneous inflight requests between peers. For the same reason, it also eliminates the need to build connection pools for your clients. It enables servers to initiate streams to clients without building any NAT traversal. muxado can also yield performance improvements (especially latency) for protocols that require rapidly opening many concurrent connections. Here's an example client which responds to simple JSON requests from a server. Maybe the client wants to make a request to the server instead of just responding. This is easy as well: muxado defines the following terms for clarity of the documentation: A "Transport" is an underlying stream (typically TCP) that is multiplexed by sending frames between muxado peers over this transport. A "Stream" is any of the full-duplex byte-streams multiplexed over the transport A "Session" is two peers running the muxado protocol over a single transport muxado's design is influenced heavily by the framing layer of HTTP2 and SPDY. However, instead of being specialized for a higher-level protocol, muxado is designed in a protocol agnostic way with simplicity and speed in mind. More advanced features are left to higher-level libraries and protocols. muxado's API is designed to make it seamless to integrate into existing Go programs. muxado.Session implements the net.Listener interface and muxado.Stream implements net.Conn. muxado ships with two wrappers that add commonly used functionality. The first is a TypedStreamSession which allows a client application to open streams with a type identifier so that the remote peer can identify the protocol that will be communicated on that stream. The second wrapper is a simple Heartbeat which issues a callback to the application informing it of round-trip latency and heartbeat failure.

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package api2 provides types and functions used to define interfaces of client-server API and facilitate creation of server and client for it. How to use this package. Organize your code in services. Each service provides some domain specific functionality. It is a Go type whose methods correspond to exposed RPC's of the API. Each method has the following signature: Let's define a service Foo with method Bar. A field must not have more than one of tags: json, query, header, cookie. Fields in query, header and cookie parts are encoded and decoded with fmt.Sprintf and fmt.Sscanf. Strings are not decoded with fmt.Sscanf, but passed as is. Types implementing encoding.TextMarshaler and encoding.TextUnmarshaler are encoded and decoded using it. Cookie in Response part must be of type http.Cookie. If no field is no JSON field in the struct, then HTTP body is skipped. You can also set HTTP status code of response by adding a field of type `int` with tag `use_as_status:"true"` to Response. 0 is interpreted as 200. If Response has status field, no HTTP statuses are considered errors. If you need the top-level type matching body JSON to be not a struct, but of some other kind (e.g. slice or map), you should provide a field in your struct with tag `use_as_body:"true"`: If you use `use_as_body:"true"`, you can also set `is_protobuf:"true"` and put a protobuf type (convertible to proto.Message) in that field. It will be sent over wire as protobuf binary form. You can add `use_as_body:"true" is_raw:"true"` to a `[]byte` field, then it will keep the whole HTTP body. Streaming. If you use `use_as_body:"true"`, you can also set `is_stream:"true"`. In this case the field must be of type `io.ReadCloser`. On the client side put any object implementing `io.ReadCloser` to such a field in Request. It will be read and closed by the library and used as HTTP request body. On the server side your handler should read from the reader passed in that field of Request. (You don't have to read the entire body and to close it.) For Response, on the server side, the handler must put any object implementing `io.ReadCloser` to such a field of Response. The library will use it to generate HTTP response's body and close it. On the client side your code must read from that reader the entire response and then close it. If a streaming field is left `nil`, it is interpreted as empty body. Now let's write the function that generates the table of routes: You can add multiple routes with the same path, but in this case their HTTP methods must be different so that they can be distinguished. If Transport is not set, DefaultTransport is used which is defined as &api2.JsonTransport{}. **Error handling**. A handler can return any Go error. `JsonTransport` by default returns JSON. `Error()` value is put into "error" field of that JSON. If the error has `HttpCode() int` method, it is called and the result is used as HTTP return code. You can pass error details (any struct). For that the error must be of a custom type. You should register the error type in `JsonTransport.Errors` map. The key used for that error is put into "code" key of JSON and the object of the registered type - into "detail" field. The error can be wrapped using `fmt.Errorf("%w" ...)`. See test/custom_error_test.go for an example. In the server you need a real instance of service Foo to pass to GetRoutes. Then just bind the routes to http.ServeMux and run the server: The server is running. It serves foo.Bar function on path /v1/foo/bar with HTTP method Post. Now let's create the client: The client sent request to path "/v1/foo/bar/product1", from which the server understood that product=product1. Note that you don't have to pass a real service object to GetRoutes on client side. You can pass nil, it is sufficient to pass all needed information about request and response types in the routes table, that is used by client to find a proper route. You can make GetRoutes accepting an interface instead of a concrete Service type. In this case you can not get method handlers by s.Bar, because this code panics if s is nil interface. As a workaround api2 provides function Method(service pointer, methodName) which you can use: If you have function GetRoutes in package foo as above you can generate static client for it in file client.go located near the file in which GetRoutes is defined: GenerateClient can accept multiple GetRoutes functions, but they must be located in the same package.

Package dnscore provides a DNS resolver, a DNS transport, a query builder, and a DNS response parser. This package is designed to facilitate DNS measurements and queries by providing both high-level and low-level APIs. It aims to be flexible, extensible, and easy to integrate with existing Go code. The high-level API provides a DNS resolver that is compatible with the net.Resolver struct from the net package. The low-level transport API allows users to send and receive DNS messages using different protocols and dialers. The package also includes utilities for creating and validating DNS messages. - High-level API compatible with *dns.Resolver for easy integration. - Low-level transport API for granular control over DNS requests and responses. - Support for multiple DNS protocols, including UDP, TCP, DoT, and DoH. - Utilities for creating and validating DNS messages. - Optional logging for structured diagnostic events. - Handling of duplicate responses for DNS over UDP to measure censorship. The package is structured to allow users to compose their own workflows by providing building blocks for DNS queries and responses. It leverages the well-tested miekg/dns library for DNS message parsing and serialization.

Package micro is a pluggable framework for microservices

Package ngrok makes it easy to work with the ngrok API from Go. The package is fully code generated and should always be up to date with the latest ngrok API. Full documentation of the ngrok API can be found at: https://ngrok.com/docs/api This package follows the best practices outlined for Go modules. All releases are tagged and any breaking changes will be reflected as a new major version. You should only import this package for production applications by pointing at a stable tagged version. The following example code demonstrates typical initialization and usage of the package to make an API call: API client configuration and all of the datatypes exchanged by the API are defined in this base package. There are subpackages for every API service and a Client type defined in those packages with methods to interact with that API service. It's usually easiest to find the subpackage of the service you want to work with and begin consulting the documentation there. It is recommended to construct the service-specific clients once at initialization time. The ClientConfig object in the root package supports functional options for configuration. The most common option to use is `WithHTTPClient()` which allows the caller to specify a different net/http.Client object. This allows the caller full customization over the transport if needed for use with proxies, custom TLS setups, observability and tracing, etc. Some arguments to methods in the ngrok API are optional and must be meaningfully distinguished from zero values, especially in Update() methods. This allows the API to distinguish between choosing not to update a value vs. setting it to zero or the empty string. For these arguments, ngrok follows the industry standard practice of using pointers to the primitive types and providing convenince functions like ngrok.String() and ngrok.Bool() for the caller to wrap literals as pointer values. For example: All List methods in the ngrok API are paged. This package abstracts that problem away from you by returning an iterator from any List API call. As you advance the iterator it will transparently fetch new pages of values for you behind the scenes. Note that the context supplied to the initial List() call will be used for all subsequent page fetches so it must be long enough to work through the entire list. Here's an example of paging through all of the TLS certificates on your account. Note that you must check for an error after Next() returns false to determine if the iterator failed to fetch the next page of results. All errors returned by the ngrok API are returned as structured payloads for easy error handling. Most non-networking errors returned by API calls in this package will be an ngrok.Error type. The ngrok.Error type exposes important metadata that will help you handle errors. Specifically it includes the HTTP status code of any failed operation as well as an error code value that uniquely identifies the failure condition. There are two helper functions that will make error handling easy: IsNotFound and IsErrorCode. IsNotFound helps identify the common case of accessing an API resource that no longer exists: IsErrorCode helps you identify specific ngrok errors by their unique ngrok error code. All ngrok error codes are documented at https://ngrok.com/docs/errors To check for a specific error condition, you would structure your code like the following example: All ngrok datatypes in this package define String() and GoString() methods so that they can be formatted into strings in helpful representations. The GoString() method is defined to pretty-print an object for debugging purposes with the "%#v" formatting verb.

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices

Package micro is a pluggable framework for microservices