Hotswap provides a solution for reloading your go code without restarting your server, interrupting or blocking any ongoing procedure.

Overview

Banner

简体中文版

Hotswap provides a solution for reloading your go code without restarting your server, interrupting or blocking any ongoing procedure. Hotswap is built upon the plugin mechanism.

Major Features

  • Reload your code like a breeze
  • Run different versions of a plugin in complete isolation
  • Invoke an in-plugin function from its host program with Plugin.InvokeFunc()
  • Expose in-plugin data and functions with PluginManager.Vault.DataBag and/or PluginManager.Vault.Extension
  • Handle asynchronous jobs using the latest code with live function, live type, and live data
  • Link plugins statically for easy debugging
  • Expose functions to other plugins with Export()
  • Depend on other plugins with Import()

Getting Started

go install github.com/edwingeng/hotswap/cli/hotswap

Build a Plugin from Source Code

Usage:
  hotswap build [flags]   -- [buildFlags]

Examples:
hotswap build plugin/foo bin
hotswap build -v plugin/foo bin -- -race
hotswap build --staticLinking plugin/foo pluginHost

Flags:
      --debug               enable the debug mode
      --exclude string      go-regexp matching files to exclude from included
      --goBuild             if --goBuild=false, skip the go build procedure (default true)
  -h, --help                help for build
      --include string      go-regexp matching files to include in addition to .go files
      --leaveTemps          do not delete temporary files
      --prefixLive string   the case-insensitive name prefix of live functions/types (default "live_")
      --staticLinking       generate code for static linking instead of building a plugin
  -v, --verbose             enable the verbose mode

Demos

You can find these examples under the demo directory. To have a direct experience, start a server with run.sh and reload its plugin(s) with reload.sh.

  1. hello demonstrates the basic usage, including how to organize host and plugin, how to build them, how to load plugin on server startup, how to use InvokeEach, and how to reload.
  2. extension shows how to define a custom extension and how to use PluginManager.Vault.Extension. A small hint: WithExtensionNewer()
  3. livex is somewhat complex. It shows how to work with live function, live type, and live data.
  4. slink is an example of plugin static-linking, with which debugging a plugin with a debugger (delve) under MacOS and Windows becomes possible.
  5. trine is the last example. It demonstrates the plugin dependency mechanism.

Required Functions

A plugin must have the following functions defined in its root package.

// OnLoad gets called after all plugins are successfully loaded and all dependencies are
// properly initialized.
func OnLoad(data interface{}) error {
    return nil
}

// OnInit gets called after the execution of all OnLoad functions.
func OnInit(sharedVault *vault.Vault) error {
    return nil
}

// OnFree gets called at some time after a reload.
func OnFree() {
}

// Export returns an object to be exported to other plugins.
func Export() interface{} {
    return nil
}

// Import returns an object indicating the dependencies of the plugin.
func Import() interface{} {
    return nil
}

// InvokeFunc invokes the specified function.
func InvokeFunc(name string, params ...interface{}) (interface{}, error) {
    return nil, nil
}

// Reloadable indicates whether the plugin is reloadable.
func Reloadable() bool {
    return true
}

Order of Execution during Plugin Reload

1. Reloadable
2. Export
3. Import
4. OnLoad
5. OnInit

Attentions

  • Build your host program with environmental variable CGO_ENABLED=1 and the -trimpath flag.
  • Version control your code with git (other VCS are not supported yet).
  • Do not define any global variable in a reloadable plugin unless it can be discarded at any time or it actually never changes.
  • Do not create any long-running goroutine in a plugin.
  • The same type in different versions of a plugin is actually not the same at runtime. Use live function, live type, and live data to avoid the trap.
  • The code of your host program should never import any package of any plugin and the code of a plugin should never import any package of other plugins.
  • Old versions won't be removed from the memory because of the limitation of golang plugin. However, Hotswap offers you a chance, the OnFree function, to clear data caches.
  • It is highly recommended to keep the code of your host program and all its plugins in a same repository.

Live Things

  • live function is a type of function whose name is prefixed with live_ (case-insensitive). Live functions are automatically collected and stored in PluginManager.Vault.LiveFuncs. For example:
func live_Foo(jobData live.Data) error {
      return nil
}
  • live type is a type of struct whose name is prefixed with live_ (case-insensitive). Live types are automatically collected and stored in PluginManager.Vault.LiveTypes. For example:
type Live_Bar struct {
      N int
}
  • live data is a type guardian. Convert your data into a live data object when scheduling an asynchronous job and restore your data from the live data object when handling the job.
  • See the demo livex for details.
Issues
Owner
Edwin
Edwin
Simple profiling for Go

profile Simple profiling for Go. Easy management of Go's built-in profiling and tracing Based on the widely-used pkg/profile: mostly-compatible API Su

Michael McLoughlin 67 Jul 14, 2021
Go tool to modify struct field tags

Go tool to modify/update field tags in structs. gomodifytags makes it easy to update, add or delete the tags in a struct field. You can easily add new tags, update existing tags (such as appending a new key, i.e: db, xml, etc..) or remove existing tags

Fatih Arslan 1.5k Jul 16, 2021
A computational topology package for gophers.

Simplices; simplicial complexes; simplicial chains; chain, cycle, boundary and homology groups; sets of simplices; methods for computing boundaries, Euler characteristics, Euler integrals, and Betti numbers, and more (with even more to come)!

Raphael Reyna 10 Apr 19, 2021
Reload Go code in a running process at function/method level granularity

got reload? Function/method-level stateful hot reloading for Go! Status Very much work in progress.

null 32 Jul 14, 2021
Get cloud instances with your favourite software pre-loaded

This Golang package can be used to provision cloud hosts using a simple CRUD-style API along with a cloud-init user-data script. It could be used to automate anything from k3s clusters, to blogs, or CI runners. We use it to create the cheapest possible hosts in the cloud with a public IP address.

inlets 20 Jul 17, 2021
Helpfully Functional Go like underscore.js

/\ \ __ __ ___ \_\ \ __ _ __ ____ ___ ___ _ __ __ __ __

null 342 Jul 14, 2021
Creates Prometheus Metrics for PolicyReports and ClusterPolicyReports. It also sends PolicyReportResults to different Targets like Grafana Loki or Slack

PolicyReporter Motivation Kyverno ships with two types of validation. You can either enforce a rule or audit it. If you don't want to block developers

Frank Jogeleit 57 Jul 15, 2021
An idiomatic Go query builder for ElasticSearch

esquery A non-obtrusive, idiomatic and easy-to-use query and aggregation builder for the official Go client for ElasticSearch. Table of Contents Descr

Aqua Security 204 Jul 14, 2021
eac3to wrapper that fixes its bug 288

eac3to-wrapper eac3to-wrapper aims to fix eac3to's long standing bug 288. To build, first install Go from golang.org/dl, then: go build -ldflags "-X m

null 5 Jul 11, 2021
Code Generation for Functional Programming, Concurrency and Generics in Golang

goderive goderive derives mundane golang functions that you do not want to maintain and keeps them up to date. It does this by parsing your go code fo

Walter Schulze 901 Jul 22, 2021
egg - the simple error aggregator

egg - the simple error aggregator egg ingests errors and aggregates them egg has 1st class support for sentry SDKs so you dont have to change any code

Joe Burnard 13 Mar 10, 2021
Concurrency in Go video course with in depth explanations & examples

Concurrency in Go Summary Coding Examples Introduction to Concurrency Go Routines Channels Select Concurrency Patterns Atomics Wait Groups - sync.Wait

Go Basics 39 Jul 24, 2021
Jennifer is a code generator for Go

Jennifer Jennifer is a code generator for Go. package main import ( "fmt" . "github.com/dave/jennifer/jen" ) func main() { f := NewFile("m

Dave Brophy 2.1k Jul 23, 2021
A tool and library for using structural regular expressions.

Structural Regular Expressions sregx is a package and tool for using structural regular expressions as described by Rob Pike (link).

Zachary Yedidia 22 Jun 18, 2021