Package context provides several utilities for working with golang.org/x/net/context in http requests. Primarily, the focus is on logging relevant request information but this package is not limited to that purpose. The easiest way to get started is to get the background context: The returned context should be passed around your application and be the root of all other context instances. If the application has a version, this line should be called before anything else: The above will store the version in the context and will be available to the logger. The most useful aspect of this package is GetLogger. This function takes any context.Context interface and returns the current logger from the context. Canonical usage looks like this: GetLogger also takes optional key arguments. The keys will be looked up in the context and reported with the logger. The following example would return a logger that prints the version with each log message: The above would print out a log message like this: When used with WithLogger, we gain the ability to decorate the context with loggers that have information from disparate parts of the call stack. Following from the version example, we can build a new context with the configured logger such that we always print the version field: Since the logger has been pushed to the context, we can now get the version field for free with our log messages. Future calls to GetLogger on the new context will have the version field: This becomes more powerful when we start stacking loggers. Let's say we have the version logger from above but also want a request id. Using the context above, in our request scoped function, we place another logger in the context: When GetLogger is called on the new context, "http.request.id" will be included as a logger field, along with the original "version" field: Note that this only affects the new context, the previous context, with the version field, can be used independently. Put another way, the new logger, added to the request context, is unique to that context and can have request scoped varaibles. This package also contains several methods for working with http requests. The concepts are very similar to those described above. We simply place the request in the context using WithRequest. This makes the request variables available. GetRequestLogger can then be called to get request specific variables in a log line: Like above, if we want to include the request data in all log messages in the context, we push the logger to a new context and use that one: The concept is fairly powerful and ensures that calls throughout the stack can be traced in log messages. Using the fields like "http.request.id", one can analyze call flow for a particular request with a simple grep of the logs.
Package uitable provides a decorator for formating data as a table
Package autorest implements an HTTP request pipeline suitable for use across multiple go-routines and provides the shared routines relied on by AutoRest (see https://github.com/Azure/autorest/) generated Go code. The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, and Responding. A typical pattern is: Each phase relies on decorators to modify and / or manage processing. Decorators may first modify and then pass the data along, pass the data first and then modify the result, or wrap themselves around passing the data (such as a logger might do). Decorators run in the order provided. For example, the following: will set the URL to: Preparers and Responders may be shared and re-used (assuming the underlying decorators support sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, all bound together by means of input / output channels. Decorators hold their passed state within a closure (such as the path components in the example above). Be careful to share Preparers and Responders only in a context where such held state applies. For example, it may not make sense to share a Preparer that applies a query string from a fixed set of values. Similarly, sharing a Responder that reads the response body into a passed struct (e.g., ByUnmarshallingJson) is likely incorrect. Lastly, the Swagger specification (https://swagger.io) that drives AutoRest (https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct parsing and formatting. Errors raised by autorest objects and methods will conform to the autorest.Error interface. See the included examples for more detail. For details on the suggested use of this package by generated clients, see the Client described below.
Package goresilience is a framework/lirbary of utilities to improve the resilience of programs easily. The library is based on `goresilience.Runner` interface, this runners can be chained using the decorator pattern (like std library `http.Handler` interface). This makes the library being extensible, flexible and clean to use. The runners can be chained like if they were middlewares that could act on all the execution process of the `goresilience.Func`. Will use a single runner, the retry with the default settings this will make the `gorunner.Func` to be executed and retried N times if it fails. Will use more than one `goresilience.Runner` and chain them to create a very resilient execution of the `goresilience.Func`. In this case we will create a runner that retries and also times out. And we will configure the timeout. Will measure all the execution through the runners uwing prometheus metrics. Is an example to show that when the result is not needed we don't need to use and inline function. Is an example to show that we could use objects aslo to pass parameter and get our results.
Package uitable provides a decorator for formating data as a table
One Tool to rule them all, One Tool to CI them, One Tool to test them all and in the darkness +1 them. Gandalf is designed to provide a language and stack agnostic HTTP API contract testing suite and prototyping toolchain. This is achieved by; running an HTTP API (aka provider), connecting to it as a real client (aka consumer) of the provider, asserting that it matches various rules (aka contracts). Optionally, once a contract is written you can then generate an approximation of the API (this happens just before the contract is tested) in the form of a mock. This allows for rapid prototyping and/or parallel development of the real consumer and provider implementations. Gandalf has no allegiance to any specific paradigms, technologies, or concepts and should bend to fit real world use cases as opposed to vice versa. This means if Gandalf does something one way today it does not mean that tomorrow it could not support a different way provided someone has a use for it. While Gandalf does use golang and the go test framework, it is not specific to go as at its core it just makes HTTP requests and checks the responses. Your web server or clients can be written in any language/framework. The official documentation also uses JSON and RESTful API's as examples but Gandalf supports any and all paradigms or styles of API. Most go programs are compiled down to a binary and executed, Gandalf is designed to be used as a library to write your own tests and decorate the test binary instead. For example, Gandalf does have several command line switches however they are provided to the `go test` command instead of some non existent `Gandalf` command. This allows Gandalf to get all kind of testing and benchmarking support for free while being a well known stable base to build upon. Contract testing can be a bit nebulous and also has various option prefixes such as Consumer Driven, Gandalf cares not for any prefixes (who writes contracts and where is up to you) nor does it care if you are testing the interface or your API or the business logic or some combination of both, no one will save you from blowing your own foot off if you choose to.
Package autorest implements an HTTP request pipeline suitable for use across multiple go-routines and provides the shared routines relied on by AutoRest (see https://github.com/Azure/autorest/) generated Go code. The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, and Responding. A typical pattern is: Each phase relies on decorators to modify and / or manage processing. Decorators may first modify and then pass the data along, pass the data first and then modify the result, or wrap themselves around passing the data (such as a logger might do). Decorators run in the order provided. For example, the following: will set the URL to: Preparers and Responders may be shared and re-used (assuming the underlying decorators support sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, all bound together by means of input / output channels. Decorators hold their passed state within a closure (such as the path components in the example above). Be careful to share Preparers and Responders only in a context where such held state applies. For example, it may not make sense to share a Preparer that applies a query string from a fixed set of values. Similarly, sharing a Responder that reads the response body into a passed struct (e.g., ByUnmarshallingJson) is likely incorrect. Lastly, the Swagger specification (https://swagger.io) that drives AutoRest (https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct parsing and formatting. Errors raised by autorest objects and methods will conform to the autorest.Error interface. See the included examples for more detail. For details on the suggested use of this package by generated clients, see the Client described below.
Package autorest implements an HTTP request pipeline suitable for use across multiple go-routines and provides the shared routines relied on by AutoRest (see https://github.com/Azure/autorest/) generated Go code. The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, and Responding. A typical pattern is: Each phase relies on decorators to modify and / or manage processing. Decorators may first modify and then pass the data along, pass the data first and then modify the result, or wrap themselves around passing the data (such as a logger might do). Decorators run in the order provided. For example, the following: will set the URL to: Preparers and Responders may be shared and re-used (assuming the underlying decorators support sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, all bound together by means of input / output channels. Decorators hold their passed state within a closure (such as the path components in the example above). Be careful to share Preparers and Responders only in a context where such held state applies. For example, it may not make sense to share a Preparer that applies a query string from a fixed set of values. Similarly, sharing a Responder that reads the response body into a passed struct (e.g., ByUnmarshallingJson) is likely incorrect. Lastly, the Swagger specification (https://swagger.io) that drives AutoRest (https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct parsing and formatting. Errors raised by autorest objects and methods will conform to the autorest.Error interface. See the included examples for more detail. For details on the suggested use of this package by generated clients, see the Client described below.
Package monkit is a flexible code instrumenting and data collection library. I'm going to try and sell you as fast as I can on this library. Example usage We've got tools that capture distribution information (including quantiles) about int64, float64, and bool types. We have tools that capture data about events (we've got meters for deltas, rates, etc). We have rich tools for capturing information about tasks and functions, and literally anything that can generate a name and a number. Almost just as importantly, the amount of boilerplate and code you have to write to get these features is very minimal. Data that's hard to measure probably won't get measured. This data can be collected and sent to Graphite (http://graphite.wikidot.com/) or any other time-series database. Here's a selection of live stats from one of our storage nodes: This library generates call graphs of your live process for you. These call graphs aren't created through sampling. They're full pictures of all of the interesting functions you've annotated, along with quantile information about their successes, failures, how often they panic, return an error (if so instrumented), how many are currently running, etc. The data can be returned in dot format, in json, in text, and can be about just the functions that are currently executing, or all the functions the monitoring system has ever seen. Here's another example of one of our production nodes: https://raw.githubusercontent.com/spacemonkeygo/monkit/master/images/callgraph2.png This library generates trace graphs of your live process for you directly, without requiring standing up some tracing system such as Zipkin (though you can do that too). Inspired by Google's Dapper (http://research.google.com/pubs/pub36356.html) and Twitter's Zipkin (http://zipkin.io), we have process-internal trace graphs, triggerable by a number of different methods. You get this trace information for free whenever you use Go contexts (https://blog.golang.org/context) and function monitoring. The output formats are svg and json. Additionally, the library supports trace observation plugins, and we've written a plugin that sends this data to Zipkin (http://github.com/spacemonkeygo/monkit-zipkin). https://raw.githubusercontent.com/spacemonkeygo/monkit/master/images/trace.png Before our crazy Go rewrite of everything (https://www.spacemonkey.com/blog/posts/go-space-monkey) (and before we had even seen Google's Dapper paper), we were a Python shop, and all of our "interesting" functions were decorated with a helper that collected timing information and sent it to Graphite. When we transliterated to Go, we wanted to preserve that functionality, so the first version of our monitoring package was born. Over time it started to get janky, especially as we found Zipkin and started adding tracing functionality to it. We rewrote all of our Go code to use Google contexts, and then realized we could get call graph information. We decided a refactor and then an all-out rethinking of our monitoring package was best, and so now we have this library. Sometimes you really want callstack contextual information without having to pass arguments through everything on the call stack. In other languages, many people implement this with thread-local storage. Example: let's say you have written a big system that responds to user requests. All of your libraries log using your log library. During initial development everything is easy to debug, since there's low user load, but now you've scaled and there's OVER TEN USERS and it's kind of hard to tell what log lines were caused by what. Wouldn't it be nice to add request ids to all of the log lines kicked off by that request? Then you could grep for all log lines caused by a specific request id. Geez, it would suck to have to pass all contextual debugging information through all of your callsites. Google solved this problem by always passing a context.Context interface through from call to call. A Context is basically just a mapping of arbitrary keys to arbitrary values that users can add new values for. This way if you decide to add a request context, you can add it to your Context and then all callsites that decend from that place will have the new data in their contexts. It is admittedly very verbose to add contexts to every function call. Painfully so. I hope to write more about it in the future, but Google also wrote up their thoughts about it (https://blog.golang.org/context), which you can go read. For now, just swallow your disgust and let's keep moving. Let's make a super simple Varnish (https://www.varnish-cache.org/) clone. Open up gedit! (Okay just kidding, open whatever text editor you want.) For this motivating program, we won't even add the caching, though there's comments for where to add it if you'd like. For now, let's just make a barebones system that will proxy HTTP requests. We'll call it VLite, but maybe we should call it VReallyLite. Run and build this and open localhost:8080 in your browser. If you use the default proxy target, it should inform you that the world hasn't been destroyed yet. The first thing you'll want to do is add the small amount of boilerplate to make the instrumentation we're going to add to your process observable later. Import the basic monkit packages: and then register environmental statistics and kick off a goroutine in your main method to serve debug requests: Rebuild, and then check out localhost:9000/stats (or localhost:9000/stats/json, if you prefer) in your browser! Remember what I said about Google's contexts (https://blog.golang.org/context)? It might seem a bit overkill for such a small project, but it's time to add them. To help out here, I've created a library that constructs contexts for you for incoming HTTP requests. Nothing that's about to happen requires my webhelp library (https://godoc.org/github.com/jtolds/webhelp), but here is the code now refactored to receive and pass contexts through our two per-request calls. You can create a new context for a request however you want. One reason to use something like webhelp is that the cancelation feature of Contexts is hooked up to the HTTP request getting canceled. Let's start to get statistics about how many requests we receive! First, this package (main) will need to get a monitoring Scope. Add this global definition right after all your imports, much like you'd create a logger with many logging libraries: Now, make the error return value of HandleHTTP named (so, (err error)), and add this defer line as the very first instruction of HandleHTTP: Let's also add the same line (albeit modified for the lack of error) to Proxy, replacing &err with nil: You should now have something like: We'll unpack what's going on here, but for now: For this new funcs dataset, if you want a graph, you can download a dot graph at localhost:9000/funcs/dot and json information from localhost:9000/funcs/json. You should see something like: with a similar report for the Proxy method, or a graph like: https://raw.githubusercontent.com/spacemonkeygo/monkit/master/images/handlehttp.png This data reports the overall callgraph of execution for known traces, along with how many of each function are currently running, the most running concurrently (the highwater), how many were successful along with quantile timing information, how many errors there were (with quantile timing information if applicable), and how many panics there were. Since the Proxy method isn't capturing a returned err value, and since HandleHTTP always returns nil, this example won't ever have failures. If you're wondering about the success count being higher than you expected, keep in mind your browser probably requested a favicon.ico. Cool, eh? How it works is an interesting line of code - there's three function calls. If you look at the Go spec, all of the function calls will run at the time the function starts except for the very last one. The first function call, mon.Task(), creates or looks up a wrapper around a Func. You could get this yourself by requesting mon.Func() inside of the appropriate function or mon.FuncNamed(). Both mon.Task() and mon.Func() are inspecting runtime.Caller to determine the name of the function. Because this is a heavy operation, you can actually store the result of mon.Task() and reuse it somehow else if you prefer, so instead of you could instead use which is more performant every time after the first time. runtime.Caller only gets called once. Careful! Don't use the same myFuncMon in different functions unless you want to screw up your statistics! The second function call starts all the various stop watches and bookkeeping to keep track of the function. It also mutates the context pointer it's given to extend the context with information about what current span (in Zipkin parlance) is active. Notably, you *can* pass nil for the context if you really don't want a context. You just lose callgraph information. The last function call stops all the stop watches ad makes a note of any observed errors or panics (it repanics after observing them). Turns out, we don't even need to change our program anymore to get rich tracing information! Open your browser and go to localhost:9000/trace/svg?regex=HandleHTTP. It won't load, and in fact, it's waiting for you to open another tab and refresh localhost:8080 again. Once you retrigger the actual application behavior, the trace regex will capture a trace starting on the first function that matches the supplied regex, and return an svg. Go back to your first tab, and you should see a relatively uninteresting but super promising svg. Let's make the trace more interesting. Add a to your HandleHTTP method, rebuild, and restart. Load localhost:8080, then start a new request to your trace URL, then reload localhost:8080 again. Flip back to your trace, and you should see that the Proxy method only takes a portion of the time of HandleHTTP! https://cdn.rawgit.com/spacemonkeygo/monkit/master/images/trace.svg There's multiple ways to select a trace. You can select by regex using the preselect method (default), which first evaluates the regex on all known functions for sanity checking. Sometimes, however, the function you want to trace may not yet be known to monkit, in which case you'll want to turn preselection off. You may have a bad regex, or you may be in this case if you get the error "Bad Request: regex preselect matches 0 functions." Another way to select a trace is by providing a trace id, which we'll get to next! Make sure to check out what the addition of the time.Sleep call did to the other reports. It's easy to write plugins for monkit! Check out our first one that exports data to Zipkin (http://zipkin.io/)'s Scribe API: https://github.com/spacemonkeygo/monkit-zipkin We plan to have more (for HTrace, OpenTracing, etc, etc), soon!
Package dctx provides several utilities for working with golang.org/x/net/context in http requests. Primarily, the focus is on logging relevent request information but this package is not limited to that purpose. The easiest way to get started is to get the background context: The returned context should be passed around your application and be the root of all other context instances. If the application has a version, this line should be called before anything else: The above will store the version in the context and will be available to the logger. The most useful aspect of this package is GetLogger. This function takes any context.Context interface and returns the current logger from the context. Canonical usage looks like this: GetLogger also takes optional key arguments. The keys will be looked up in the context and reported with the logger. The following example would return a logger that prints the version with each log message: The above would print out a log message like this: When used with WithLogger, we gain the ability to decorate the context with loggers that have information from disparate parts of the call stack. Following from the version example, we can build a new context with the configured logger such that we always print the version field: Since the logger has been pushed to the context, we can now get the version field for free with our log messages. Future calls to GetLogger on the new context will have the version field: This becomes more powerful when we start stacking loggers. Let's say we have the version logger from above but also want a request id. Using the context above, in our request scoped function, we place another logger in the context: When GetLogger is called on the new context, "http.request.id" will be included as a logger field, along with the original "version" field: Note that this only affects the new context, the previous context, with the version field, can be used independently. Put another way, the new logger, added to the request context, is unique to that context and can have request scoped varaibles. This package also contains several methods for working with http requests. The concepts are very similar to those described above. We simply place the request in the context using WithRequest. This makes the request variables available. GetRequestLogger can then be called to get request specific variables in a log line: Like above, if we want to include the request data in all log messages in the context, we push the logger to a new context and use that one: The concept is fairly powerful and ensures that calls throughout the stack can be traced in log messages. Using the fields like "http.request.id", one can analyze call flow for a particular request with a simple grep of the logs.
Package context provides several utilities for working with golang.org/x/net/context in http requests. Primarily, the focus is on logging relevant request information but this package is not limited to that purpose. The easiest way to get started is to get the background context: The returned context should be passed around your application and be the root of all other context instances. If the application has a version, this line should be called before anything else: The above will store the version in the context and will be available to the logger. The most useful aspect of this package is GetLogger. This function takes any context.Context interface and returns the current logger from the context. Canonical usage looks like this: GetLogger also takes optional key arguments. The keys will be looked up in the context and reported with the logger. The following example would return a logger that prints the version with each log message: The above would print out a log message like this: When used with WithLogger, we gain the ability to decorate the context with loggers that have information from disparate parts of the call stack. Following from the version example, we can build a new context with the configured logger such that we always print the version field: Since the logger has been pushed to the context, we can now get the version field for free with our log messages. Future calls to GetLogger on the new context will have the version field: This becomes more powerful when we start stacking loggers. Let's say we have the version logger from above but also want a request id. Using the context above, in our request scoped function, we place another logger in the context: When GetLogger is called on the new context, "http.request.id" will be included as a logger field, along with the original "version" field: Note that this only affects the new context, the previous context, with the version field, can be used independently. Put another way, the new logger, added to the request context, is unique to that context and can have request scoped varaibles. This package also contains several methods for working with http requests. The concepts are very similar to those described above. We simply place the request in the context using WithRequest. This makes the request variables available. GetRequestLogger can then be called to get request specific variables in a log line: Like above, if we want to include the request data in all log messages in the context, we push the logger to a new context and use that one: The concept is fairly powerful and ensures that calls throughout the stack can be traced in log messages. Using the fields like "http.request.id", one can analyze call flow for a particular request with a simple grep of the logs.
Package cache is a caching library which allows functionality to be decorated onto basic caches
rowm is a hybrid tiling manager aiming to replicate the ergonomics of terminator and tmux. For more information on the usage, please read the README instead. main.go - entrypoint, initializes connection to X and connects root callbacks root/ - callbacks for the root window are defined here frame/ - the majority of the logic is in this folder, defines the tree window structure and wrapping decorations sideloop/ - utilities for running code in line with the X event loop from xgbutil resources/ - non compiled data resources cmd/rowmbright/ - a utility for changing backlight brightness without root privileges ext/ - misc bits and bobs missing in either the standard library or xgbutil dev.sh - starts up a container for developing in (required for running compile.sh or test.sh) compile.sh - go gets/builds rowm in container clean.sh - gets rid of container created by dev.sh exec.sh - execs into container created by dev.sh install.sh - (requires root) builds rowm and installs files to the system (only tested on ubuntu18.04) test.sh - (requires xephyr to be installed and dev.sh to have been run) opens a nested x server with rowm loaded for trying out
Package flow provides support for very basic FBP / pipelines. Each handler represents async stage consuming data from the input channel and publishing results to the output channel. Each handler runs in separate goroutines. User must implement Handler function and add it to the Flow. Each handler usually creates an output channel, reads from the input channel, processes data and sends results to the output channel. Processing sequence defined by order of those handlers. Any Handler can run in multiple concurrent goroutines (workers) by using the Parallel decorator. FanOut allows to pass multiple handlers in the broadcast mode, i.e., each handler gets every input record. Outputs from these handlers merged and combined into a single output channel. Processing error detected as return error value from user's handler func. Such error interrupts all other running handlers gracefully and won't keep any goroutine running/leaking. Each Flow object can be executed only once. Handler has to handle context cancellation as a termination signal.
The render package helps manage HTTP request and response payloads. Every well-designed, robust and maintainable Web Service / REST API also needs well-defined request and payloads. Together with the endpoint handler, the request and response payloads make up the contract between your server and the clients calling on it. Typically in a REST API application, you will have data models (objects/structs) that hold lower-level runtime application state, and at time you need to assemble, decorate hide or transform the representation before responding to a client. That server output (response payload) structure, is likely the input structure to another handler on the server. This is where render comes in - offering a few simple helpers and to provide a simple pattern for managing payload encoding and decoding.
Package autorest implements an HTTP request pipeline suitable for use across multiple go-routines and provides the shared routines relied on by AutoRest (see https://github.com/Azure/autorest/) generated Go code. The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, and Responding. A typical pattern is: Each phase relies on decorators to modify and / or manage processing. Decorators may first modify and then pass the data along, pass the data first and then modify the result, or wrap themselves around passing the data (such as a logger might do). Decorators run in the order provided. For example, the following: will set the URL to: Preparers and Responders may be shared and re-used (assuming the underlying decorators support sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, all bound together by means of input / output channels. Decorators hold their passed state within a closure (such as the path components in the example above). Be careful to share Preparers and Responders only in a context where such held state applies. For example, it may not make sense to share a Preparer that applies a query string from a fixed set of values. Similarly, sharing a Responder that reads the response body into a passed struct (e.g., ByUnmarshallingJson) is likely incorrect. Lastly, the Swagger specification (https://swagger.io) that drives AutoRest (https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct parsing and formatting. Errors raised by autorest objects and methods will conform to the autorest.Error interface. See the included examples for more detail. For details on the suggested use of this package by generated clients, see the Client described below.
Package decor contains a simple-to-user yet powerful template loader mainly focussed on the golang built-in templates text/template and html/template. While these packages provide powerful templating facilities with great support for rendering textual content, using these packages to build a complete layout-based template solution involves a lot of boilerplate code. decor tries to fill this gap by providing just what's needed to reduce the boilerplate and enable a great developer experience.
Package uitable provides a decorator for formating data as a table
Package autorest implements an HTTP request pipeline suitable for use across multiple go-routines and provides the shared routines relied on by AutoRest (see https://github.com/Azure/autorest/) generated Go code. The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, and Responding. A typical pattern is: Each phase relies on decorators to modify and / or manage processing. Decorators may first modify and then pass the data along, pass the data first and then modify the result, or wrap themselves around passing the data (such as a logger might do). Decorators run in the order provided. For example, the following: will set the URL to: Preparers and Responders may be shared and re-used (assuming the underlying decorators support sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, all bound together by means of input / output channels. Decorators hold their passed state within a closure (such as the path components in the example above). Be careful to share Preparers and Responders only in a context where such held state applies. For example, it may not make sense to share a Preparer that applies a query string from a fixed set of values. Similarly, sharing a Responder that reads the response body into a passed struct (e.g., ByUnmarshallingJson) is likely incorrect. Lastly, the Swagger specification (https://swagger.io) that drives AutoRest (https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct parsing and formatting. Errors raised by autorest objects and methods will conform to the autorest.Error interface. See the included examples for more detail. For details on the suggested use of this package by generated clients, see the Client described below.
Package degorator implements the decorator pattern in golang. This can be used to add behavior, such as logs or metrics, into a function without affecting the original behavior at runtime.
Package context provides several utilities for working with golang.org/x/net/context in http requests. Primarily, the focus is on logging relevant request information but this package is not limited to that purpose. The easiest way to get started is to get the background context: The returned context should be passed around your application and be the root of all other context instances. If the application has a version, this line should be called before anything else: The above will store the version in the context and will be available to the logger. The most useful aspect of this package is GetLogger. This function takes any context.Context interface and returns the current logger from the context. Canonical usage looks like this: GetLogger also takes optional key arguments. The keys will be looked up in the context and reported with the logger. The following example would return a logger that prints the version with each log message: The above would print out a log message like this: When used with WithLogger, we gain the ability to decorate the context with loggers that have information from disparate parts of the call stack. Following from the version example, we can build a new context with the configured logger such that we always print the version field: Since the logger has been pushed to the context, we can now get the version field for free with our log messages. Future calls to GetLogger on the new context will have the version field: This becomes more powerful when we start stacking loggers. Let's say we have the version logger from above but also want a request id. Using the context above, in our request scoped function, we place another logger in the context: When GetLogger is called on the new context, "http.request.id" will be included as a logger field, along with the original "version" field: Note that this only affects the new context, the previous context, with the version field, can be used independently. Put another way, the new logger, added to the request context, is unique to that context and can have request scoped varaibles. This package also contains several methods for working with http requests. The concepts are very similar to those described above. We simply place the request in the context using WithRequest. This makes the request variables available. GetRequestLogger can then be called to get request specific variables in a log line: Like above, if we want to include the request data in all log messages in the context, we push the logger to a new context and use that one: The concept is fairly powerful and ensures that calls throughout the stack can be traced in log messages. Using the fields like "http.request.id", one can analyze call flow for a particular request with a simple grep of the logs.
"jst" -- JSON Table -- is a format that's parsable as JSON, while sprucing up the display to humans using the non-significant whitespace cleverly. Regular data can be piped into a JSON Table formatter, and some simple heuristics will attempt to detect table structure. Lists can be turned into column-aligned tables: Maps can also be turned into column-aligned tables: Decorations can be applied: The overall nature of detecting traits of the data (particularly, size) means JSON Tables cannot be created streamingly; we have to process the entire structure first, and only then can we begin to output correctly aligned data. (It's for this reason that this is implemented over IPLD Nodes, and would be somewhat painful to implement using just refmt Tokens -- we'd end up buffering *all* the tokens anyway, and wanting to build an index, etc.) There's no unmarshal functions because unmarshal is just... regular JSON unmarshal.
termdeco is a small library for cross-platform console text decoration. It provides functions for text decoration, Formatter, that can be used with fmt.Printf like (Fprintf, Sprintf etc.) functions like In this case, v is printed with red, bold text (on Windows, bold is translated into text brighter) on green background. It also provides wrappers for functions in fmt package. For cross-platform compatibility, it is recommended using these wrappers for printing decorated text like It implements following ANSI compatible decoration. Black, Red, Green, Yellow, Blue, Magenta, Cyan, White text and background colors. Bright Black, Bright Red, Bright Green, Bright Yellow, Bright Blue, Bright Magenta, Bright Cyan, Bright White text and background colors Those decoration is implemented as a function of its name whith returns Decoration type Formatter so it can be called in a chain like and latter called method overwrites previous one, for example, applies red and after that it overwrites so text printed as green
Package decorate contains various helpers to decorate errors with fewer lines of code in functions.
Package uitable provides a decorator for formating data as a table
Package cache is a caching library which allows functionality to be decorated onto basic caches
rowm is a hybrid tiling manager aiming to replicate the ergonomics of terminator and tmux. For more information on the usage, please read the README instead. main.go - entrypoint, initializes connection to X and connects root callbacks root/ - callbacks for the root window are defined here frame/ - the majority of the logic is in this folder, defines the tree window structure and wrapping decorations sideloop/ - utilities for running code in line with the X event loop from xgbutil resources/ - non compiled data resources cmd/rowmbright/ - a utility for changing backlight brightness without root privileges ext/ - misc bits and bobs missing in either the standard library or xgbutil dev.sh - starts up a container for developing in (required for running compile.sh or test.sh) compile.sh - go gets/builds rowm in container clean.sh - gets rid of container created by dev.sh exec.sh - execs into container created by dev.sh install.sh - (requires root) builds rowm and installs files to the system (only tested on ubuntu18.04) test.sh - (requires xephyr to be installed and dev.sh to have been run) opens a nested x server with rowm loaded for trying out
Package queue provides a deferrableDecorator queue implementation that supports reflectionJob retires and deferred dispatch. It is recommended to read documentation on the core package before getting started on the queue package. Queues in go is not as prominent as in some other languages, since go excels at handling concurrency. However, the deferrableDecorator queue can still offer some benefit missing from the native mechanism, say go channels. The queued reflectionJob won't be lost even if the system shutdown. In other words, it means jobs can be retried until success. Plus, it is also possible to queue the execution of a particular reflectionJob until a lengthy period of time. Useful when you need to implement "send email after 30 days" type of Job handler. First and foremost we should create a reflectionJob, waiting the queue to dispatch. A reflectionJob can be any struct that implements the Job interface. Although the object that implements the reflectionJob interface can be dispatched immediately, it only minimally describes the reflectionJob's property . We can tune the properties with the Adjust helper. For example, we want to run the reflectionJob after 3 minutes with maximum 5 retries: Like the Job package, you don't have to use this helper. Manually create a queueable Job by implementing this interface on top of the normal Job interface: The PersistentJob passed to the Decorate method contains the tunable configuration such as maximum retries. No matter how you create a persisted Job, to fire it, send it though a dispatcher. The normal dispatcher in the Jobs package won't work, as a queue implementation is required. Luckily, it is deadly simple to convert a standard dispatcher to a queue.JobDispatcher. As you can see, how the queue persist the Jobs is subject to the underlying driver. The default driver bundled in this package is the redis driver. Once the persisted Job are stored in the external storage, a goroutine should consume them and pipe the reconstructed Job to the listeners. This is done by calling the Consume method JobFrom queue.JobDispatcher Note if a Job is retryable, it is your responsibility to ensure the idempotency. Also, be aware if a persisted Job have many listeners, the Job is up to retry when any of the listeners fail. The queue package exports configuration in this format: While manually constructing the queue.JobDispatcher is absolutely feasible, users can use the bundled dependency provider without breaking a sweat. Using this approach, the life cycle of consumer goroutine will be managed automatically by the core. A module is also bundled, providing the queue command (for reloading and flushing). Sometimes there are valid reasons to use more than one queue. Each dispatcher however is bounded to only one queue. To use multiple queues, multiple dispatchers are required. Inject queue.DispatcherMaker to factory a dispatcher with a specific name. When an attempt to execute the Job handler failed, two kinds of special eventDispatcher-based Job will be fired. If the failed Job can be retried, "queue.RetryingJob" will be fired. If not, "queue.AbortedJob" will be fired. To gain visibility on how the length of the queue, inject a gauge into the core and alias it to queue.Gauge. The queue length of the all internal queues will be periodically reported to metrics collector (Presumably Prometheus).
Package decor provides facilities for decorating a string of characters with display attributes for the current (or specified) terminal type. This is done using a notation inspired by (but slightly different from) Zsh prompt formatting. Supported attributes are bold, italic, and/or underlined characters as well as 256-color support for foreground and background colors. As a simple example, the numbered markings in the decor notated string argument to the Format method here: ...each have the following meaning. Therefore, the value assigned to s would be the string "user@host" - formatted for the current terminal - in all bold text with "user" displayed in italics and foreground color DarkTurquoise, the '@' character with color Orchid1, and "host" shown with color Green3. Or more specifically, for TERM="xterm-256color", the value of s would be: All attribute designators begin with an '@' sign (for "ATtribute"); a literal '@' sign is specified as two consecutive characters (e.g. "@@"). The '@' sign is immediately followed by one of several capital letters to begin the attribute or a lower case letter to end that attribute. The full list of supported attribute designators is as follows: The start-color designators (@F and @K) are then followed by a color name or number wrapped in braces (such as "@F{DodgerBlue}"). Note that the braces surrounding the color name (or number) are not limited to '{' and '}'; these can be any matching pair of brace-like characters (i.e. "<color>", "color" or "(color)") -or- any character at all, such that the beginning and ending characters agree (e.g. "@F+color+"). See package toolman.org/terminal/decor/color for a complete list of supported color names. In addition to simple string decoration, this package also supports variable expansion through templates. The example above could be modified to instead create a template like so: Here, the template's Expand method is provided a map of variable names and values for "${UserName}", "${HostName}", and "${Domain}" which are expanded to format the template for the current terminal. Note that values for template variable may reference other variables (as above where ${HostName} references ${Domain}) and can themselves contain attribute designations (as ${HostName} uses a difference color for ${Domain}). Special care is taken to restore attributes after a variable expansion that were in effect before the expansion started and unnecessary or redundant attributes are optimized away. For example, if a template specifies a foreground color of "SpringGreen" and a variable changes the foreground color to "DarkCyan", the foreground color will be restored to "SpringGreen" once the variable has been expanded.
Package psv converts arrays of structs or maps into pretty, pipe-separated text tables, and vice-versa. Example Output The table data and appearance can be set up via any of the following examples: This package focusses on data representation, human readability and the exchange of intentions, which a computer may incidentally be able to make sense of. Mostly, each cell of a table is a simple, single string value, however, with a bit of additional work, the string values may be mapped to slices or maps of slightly more complicated (incl. custom) structures. The lack of support for every last, complicated, nested structure is intentional. There a large number of csv, tsv, dsv packages availble on pkg.go.dev, but they all seem to concentrate on "machine readable data exchange". Nevertheless, they served as inspiration for this package as well. psv always *felt* like a package I should not have to write, but I was unable to find an existing program with suitable features: - simple to use, suitable for as an editor plugin / shell pipe - align columnated data - while ignoring lines which aren't columnated The unix tools [column] and [tbl] and go's own encoding/csv package all served as a good basis, but they all follow different goals. Table is the central struct provided by psv. With a Table struct you can then add rows of data as well as Decorations (non-table rows to be interspersed before, between or after the data rows) and additional formatting such as indents. The table parser expects an bufio.Scanner, from which it will extract all rows of data (beginning with a '|' character), while retaining enough information to re-construct the original text it was given. For convenience, psv.TableFromString() may be used to parse in-situ tables, ideal for testing etc. e.g.
Package nrlogrusplugin decorates logs for sending to the New Relic backend. Use this package if you already send your logs to New Relic and want to enable linking between your APM events and traces with your logs. Since Logrus is completely api-compatible with the stdlib logger, you can replace your `"log"` imports with `log "github.com/sirupsen/logrus"` and follow the steps below to enable the logging product for use with the stdlib Go logger. Using `logger.WithField` (https://godoc.org/github.com/sirupsen/logrus#Logger.WithField) and `logger.WithFields` (https://godoc.org/github.com/sirupsen/logrus#Logger.WithFields) is supported. However, if the field key collides with one of the keys used by the New Relic Formatter, the value will be overwritten. Reserved keys are those found in the `logcontext` package (https://godoc.org/github.com/edwardofclt/newrelic-go-agent/v3/integrations/logcontext/#pkg-constants). Supported types for `logger.WithField` and `logger.WithFields` field values are numbers, booleans, strings, and errors. Func types are dropped and all other types are converted to strings. Requires v1.4.0 of the Logrus package or newer. For the best linking experience be sure to enable Distributed Tracing: To enable log decoration, set your log's formatter to the `nrlogrusplugin.ContextFormatter` or if you are using the logrus standard logger The logger will now look for a newrelic.Transaction inside its context and decorate logs accordingly. Therefore, the Transaction must be added to the context and passed to the logger. For example, this logging call must be transformed to include the context, such as: When properly configured, your log statements will be in JSON format with one message per line: If the `trace.id` key is missing, be sure that Distributed Tracing is enabled and that the Transaction context has been added to the logger using `WithContext` (https://godoc.org/github.com/sirupsen/logrus#Logger.WithContext).