Library documentation (#8)

* code and readme docs update

* readme update

README.md

@@ -1,5 +1,182 @@
 # go-mpatch
 Go library for monkey patching
 
+## Compatibility
 
-Library inspired by the blog post: https://bou.ke/blog/monkey-patching-in-go/
+- **Go version:** tested from `go1.7` to `go1.15-beta`
+- **Architectures:** `x86`, `amd64`
+- **Operating systems:** tested in `macos`, `linux` and `windows`. 
+
+## Features
+
+- Can patch package functions, instance functions (by pointer or by value), and create new functions from scratch.
+
+## Limitations
+
+- Target functions could be inlined, making those functions unpatcheables. You can use `//go:noinline` directive or build with the `gcflags=-l`
+to disable inlining at compiler level.
+
+- Write permission to memory pages containing executable code is needed, some operating systems could restrict this access.
+
+- Not thread safe.
+
+## Usage
+
+### Patching a func
+```go
+//go:noinline
+func methodA() int { return 1 }
+
+//go:noinline
+func methodB() int { return 2 }
+
+func TestPatcher(t *testing.T) {
+ patch, err := mpatch.PatchMethod(methodA, methodB)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if methodA() != 2 {
+ t.Fatal("The patch did not work")
+ }
+
+ err = patch.Unpatch()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if methodA() != 1 {
+ t.Fatal("The unpatch did not work")
+ }
+}
+```
+
+### Patching using `reflect.ValueOf`
+```go
+//go:noinline
+func methodA() int { return 1 }
+
+//go:noinline
+func methodB() int { return 2 }
+
+func TestPatcherUsingReflect(t *testing.T) {
+ reflectA := reflect.ValueOf(methodA)
+ patch, err := mPatch.PatchMethodByReflect(reflectA, methodB)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if methodA() != 2 {
+ t.Fatal("The patch did not work")
+ }
+
+ err = patch.Unpatch()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if methodA() != 1 {
+ t.Fatal("The unpatch did not work")
+ }
+}
+```
+
+### Patching creating a new func at runtime
+```go
+//go:noinline
+func methodA() int { return 1 }
+
+func TestPatcherUsingMakeFunc(t *testing.T) {
+ reflectA := reflect.ValueOf(methodA)
+ patch, err := PatchMethodWithMakeFunc(reflectA,
+ func(args []reflect.Value) (results []reflect.Value) {
+ return []reflect.Value{reflect.ValueOf(42)}
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if methodA() != 42 {
+ t.Fatal("The patch did not work")
+ }
+
+ err = patch.Unpatch()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if methodA() != 1 {
+ t.Fatal("The unpatch did not work")
+ }
+}
+```
+
+### Patching an instance func
+```go
+type myStruct struct {
+}
+
+//go:noinline
+func (s *myStruct) Method() int {
+ return 1
+}
+
+func TestInstancePatcher(t *testing.T) {
+ mStruct := myStruct{}
+
+ var patch *Patch
+ var err error
+ patch, err = PatchInstanceMethodByName(reflect.TypeOf(mStruct), "Method", func(m *myStruct) int {
+ patch.Unpatch()
+ defer patch.Patch()
+ return 41 + m.Method()
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if mStruct.Method() != 42 {
+ t.Fatal("The patch did not work")
+ }
+ err = patch.Unpatch()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if mStruct.Method() != 1 {
+ t.Fatal("The unpatch did not work")
+ }
+}
+```
+
+### Patching an instance func by Value
+```go
+type myStruct struct {
+}
+
+//go:noinline
+func (s myStruct) ValueMethod() int {
+ return 1
+}
+
+func TestInstanceValuePatcher(t *testing.T) {
+ mStruct := myStruct{}
+
+ var patch *Patch
+ var err error
+ patch, err = PatchInstanceMethodByName(reflect.TypeOf(mStruct), "ValueMethod", func(m myStruct) int {
+ patch.Unpatch()
+ defer patch.Patch()
+ return 41 + m.Method()
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if mStruct.ValueMethod() != 42 {
+ t.Fatal("The patch did not work")
+ }
+ err = patch.Unpatch()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if mStruct.ValueMethod() != 1 {
+ t.Fatal("The unpatch did not work")
+ }
+}
+```
+
+> Library inspired by the blog post: https://bou.ke/blog/monkey-patching-in-go/

patcher.go

@@ -31,6 +31,7 @@ var (
  pageSize = syscall.Getpagesize()
 )
 
+// Patches a target func to redirect calls to "redirection" func. Both function must have same arguments and return types.
 func PatchMethod(target, redirection interface{}) (*Patch, error) {
  tValue := getValueFrom(target)
  rValue := getValueFrom(redirection)
@@ -43,6 +44,8 @@ func PatchMethod(target, redirection interface{}) (*Patch, error) {
  }
  return patch, nil
 }
+// Patches an instance func by using two parameters, the target struct type and the method name inside that type,
+//this func will be redirected to the "redirection" func. Note: The first parameter of the redirection func must be the object instance.
 func PatchInstanceMethodByName(target reflect.Type, methodName string, redirection interface{}) (*Patch, error) {
  method, ok := target.MethodByName(methodName)
  if !ok && target.Kind() == reflect.Struct {
@@ -54,6 +57,8 @@ func PatchInstanceMethodByName(target reflect.Type, methodName string, redirecti
  }
  return PatchMethodByReflect(method.Func, redirection)
 }
+// Patches a target func by passing the reflect.ValueOf of the func. The target func will be redirected to the "redirection" func.
+// Both function must have same arguments and return types.
 func PatchMethodByReflect(target reflect.Value, redirection interface{}) (*Patch, error) {
  tValue := &target
  rValue := getValueFrom(redirection)
@@ -66,10 +71,11 @@ func PatchMethodByReflect(target reflect.Value, redirection interface{}) (*Patch
  }
  return patch, nil
 }
+// Patches a target func with a "redirection" function created at runtime by using "reflect.MakeFunc".
 func PatchMethodWithMakeFunc(target reflect.Value, fn func(args []reflect.Value) (results []reflect.Value)) (*Patch, error) {
  return PatchMethodByReflect(target, reflect.MakeFunc(target.Type(), fn))
 }
-
+// Patch the target func with the redirection func.
 func (p *Patch) Patch() error {
  if p == nil {
  return errors.New("patch is nil")
@@ -82,6 +88,7 @@ func (p *Patch) Patch() error {
  }
  return nil
 }
+// Unpatch the target func and recover the original func.
 func (p *Patch) Unpatch() error {
  if p == nil {
  return errors.New("patch is nil")
@@ -96,7 +103,7 @@ func isPatchable(target, redirection *reflect.Value) error {
  if target.Type() != redirection.Type() {
  return errors.New(fmt.Sprintf("the target and/or redirection doesn't have the same type: %s != %s", target.Type(), redirection.Type()))
  }
- if _, ok := patches[getSafeCodePointer(target)]; ok {
+ if _, ok := patches[getCodePointer(target)]; ok {
  return errors.New("the target is already patched")
  }
  return nil
@@ -105,7 +112,7 @@ func isPatchable(target, redirection *reflect.Value) error {
 func applyPatch(patch *Patch) error {
  patchLock.Lock()
  defer patchLock.Unlock()
- tPointer := getSafeCodePointer(patch.target)
+ tPointer := getCodePointer(patch.target)
  rPointer := getInternalPtrFromValue(patch.redirection)
  rPointerJumpBytes, err := getJumpFuncBytes(rPointer)
  if err != nil {
@@ -114,7 +121,7 @@ func applyPatch(patch *Patch) error {
  tPointerBytes := getMemorySliceFromPointer(tPointer, len(rPointerJumpBytes))
  targetBytes := make([]byte, len(tPointerBytes))
  copy(targetBytes, tPointerBytes)
- if err := copyDataToPtr(tPointer, rPointerJumpBytes); err != nil {
+ if err := writeDataToPointer(tPointer, rPointerJumpBytes); err != nil {
  return err
  }
  patch.targetBytes = targetBytes
@@ -128,12 +135,12 @@ func applyUnpatch(patch *Patch) error {
  if patch.targetBytes == nil || len(patch.targetBytes) == 0 {
  return errors.New("the target is not patched")
  }
- tPointer := getSafeCodePointer(patch.target)
+ tPointer := getCodePointer(patch.target)
  if _, ok := patches[tPointer]; !ok {
  return errors.New("the target is not patched")
  }
  delete(patches, tPointer)
- err := copyDataToPtr(tPointer, patch.targetBytes)
+ err := writeDataToPointer(tPointer, patch.targetBytes)
  if err != nil {
  return err
  }
@@ -148,6 +155,7 @@ func getValueFrom(data interface{}) reflect.Value {
  }
 }
 
+// Extracts a memory slice from a pointer
 func getMemorySliceFromPointer(p unsafe.Pointer, length int) []byte {
  return *(*[]byte)(unsafe.Pointer(&sliceHeader{
  Data: p,
@@ -156,7 +164,8 @@ func getMemorySliceFromPointer(p unsafe.Pointer, length int) []byte {
  }))
 }
 
-func getSafeCodePointer(value *reflect.Value) unsafe.Pointer {
+// Gets the code pointer of a func
+func getCodePointer(value *reflect.Value) unsafe.Pointer {
  p := getInternalPtrFromValue(value)
  if p != nil {
  p = *(*unsafe.Pointer)(p)

patcher_test.go

@@ -45,7 +45,8 @@ func TestPatcher(t *testing.T) {
 }
 
 func TestPatcherUsingReflect(t *testing.T) {
- patch, err := PatchMethodByReflect(reflect.ValueOf(methodA), methodB)
+ reflectA := reflect.ValueOf(methodA)
+ patch, err := PatchMethodByReflect(reflectA, methodB)
  if err != nil {
  t.Fatal(err)
  }
@@ -63,9 +64,11 @@ func TestPatcherUsingReflect(t *testing.T) {
 }
 
 func TestPatcherUsingMakeFunc(t *testing.T) {
- patch, err := PatchMethodWithMakeFunc(reflect.ValueOf(methodA), func(args []reflect.Value) (results []reflect.Value) {
- return []reflect.Value{reflect.ValueOf(42)}
- })
+ reflectA := reflect.ValueOf(methodA)
+ patch, err := PatchMethodWithMakeFunc(reflectA,
+ func(args []reflect.Value) (results []reflect.Value) {
+ return []reflect.Value{reflect.ValueOf(42)}
+ })
  if err != nil {
  t.Fatal(err)
  }

patcher_unix.go

@@ -31,7 +31,7 @@ func callMProtect(addr unsafe.Pointer, length int, prot int) error {
  return nil
 }
 
-func copyDataToPtr(ptr unsafe.Pointer, data []byte) error {
+func writeDataToPointer(ptr unsafe.Pointer, data []byte) error {
  dataLength := len(data)
  ptrByteSlice := getMemorySliceFromPointer(ptr, len(data))
  if err := callMProtect(ptr, dataLength, writeAccess); err != nil {

patcher_windows.go

@@ -19,7 +19,7 @@ func callVirtualProtect(lpAddress unsafe.Pointer, dwSize int, flNewProtect uint3
  return nil
 }
 
-func copyDataToPtr(ptr unsafe.Pointer, data []byte) error {
+func writeDataToPointer(ptr unsafe.Pointer, data []byte) error {
  var oldPerms, tmp uint32
  dataLength := len(data)
  ptrByteSlice := getMemorySliceFromPointer(ptr, len(data))