Generate varlink API documentation automatically

Using varlink's idl parser, we generate API documentation for the podman
API relying on the .varlink file as the source.

Signed-off-by: baude <bbaude@redhat.com>

Closes: #734
Approved by: baude

vendor/github.com/varlink/go/cmd/varlink-go-certification/main.go

@@ -0,0 +1,619 @@
+package main
+
+import (
+	"crypto/rand"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"github.com/varlink/go/cmd/varlink-go-certification/orgvarlinkcertification"
+	"github.com/varlink/go/varlink"
+	"io"
+	"math"
+	"os"
+	"strconv"
+	"sync"
+	"time"
+)
+
+func run_client(address string) {
+	c, err := varlink.NewConnection(address)
+	if err != nil {
+		fmt.Println("Failed to connect")
+		return
+	}
+	defer c.Close()
+
+	client_id, err := orgvarlinkcertification.Start().Call(c)
+	if err != nil {
+		fmt.Println("Start() failed")
+		return
+	}
+	fmt.Printf("Start: '%v'\n", client_id)
+
+	b1, err := orgvarlinkcertification.Test01().Call(c, client_id)
+	if err != nil {
+		fmt.Println("Test01() failed")
+		return
+	}
+	fmt.Printf("Test01: '%v'\n", b1)
+
+	i2, err := orgvarlinkcertification.Test02().Call(c, client_id, b1)
+	if err != nil {
+		fmt.Println("Test02() failed")
+		return
+	}
+	fmt.Printf("Test02: '%v'\n", i2)
+
+	f3, err := orgvarlinkcertification.Test03().Call(c, client_id, i2)
+	if err != nil {
+		fmt.Println("Test03() failed")
+		return
+	}
+	fmt.Printf("Test03: '%v'\n", f3)
+
+	s4, err := orgvarlinkcertification.Test04().Call(c, client_id, f3)
+	if err != nil {
+		fmt.Println("Test04() failed")
+		return
+	}
+	fmt.Printf("Test04: '%v'\n", s4)
+
+	b5, i5, f5, s5, err := orgvarlinkcertification.Test05().Call(c, client_id, s4)
+	if err != nil {
+		fmt.Println("Test05() failed")
+		return
+	}
+	fmt.Printf("Test05: '%v'\n", b5)
+
+	o6, err := orgvarlinkcertification.Test06().Call(c, client_id, b5, i5, f5, s5)
+	if err != nil {
+		fmt.Println("Test06() failed")
+		return
+	}
+	fmt.Printf("Test06: '%v'\n", o6)
+
+	m7, err := orgvarlinkcertification.Test07().Call(c, client_id, o6)
+	if err != nil {
+		fmt.Println("Test07() failed")
+		return
+	}
+	fmt.Printf("Test07: '%v'\n", m7)
+
+	m8, err := orgvarlinkcertification.Test08().Call(c, client_id, m7)
+	if err != nil {
+		fmt.Println("Test08() failed")
+		return
+	}
+	fmt.Printf("Test08: '%v'\n", m8)
+
+	t9, err := orgvarlinkcertification.Test09().Call(c, client_id, m8)
+	if err != nil {
+		fmt.Println("Test09() failed")
+		return
+	}
+	fmt.Printf("Test09: '%v'\n", t9)
+
+	receive10, err := orgvarlinkcertification.Test10().Send(c, varlink.More, client_id, t9)
+	if err != nil {
+		fmt.Println("Test10() failed")
+		return
+	}
+
+	fmt.Println("Test10() Send:")
+	var a10 []string
+	for {
+		s10, flags10, err := receive10()
+		if err != nil {
+			fmt.Println("Test10() receive failed")
+			return
+		}
+		a10 = append(a10, s10)
+		fmt.Printf("  Receive: '%v'\n", s10)
+
+		if flags10&varlink.Continues == 0 {
+			break
+		}
+	}
+	fmt.Printf("Test10: '%v'\n", a10)
+
+	_, err = orgvarlinkcertification.Test11().Send(c, varlink.Oneway, client_id, a10)
+	if err != nil {
+		fmt.Println("Test11() failed")
+		return
+	}
+	fmt.Println("Test11: ''")
+
+	end, err := orgvarlinkcertification.End().Call(c, client_id)
+	if err != nil {
+		fmt.Println("End() failed")
+		return
+	}
+	fmt.Printf("End: '%v'\n", end)
+}
+
+// Service
+type client struct {
+	id   string
+	time time.Time
+}
+
+type test struct {
+	orgvarlinkcertification.VarlinkInterface
+	mutex   sync.Mutex
+	clients map[string]*client
+}
+
+func (t *test) Client(id string) *client {
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+
+	return t.clients[id]
+}
+
+func (t *test) NewClient() *client {
+	id128 := make([]byte, 16)
+	io.ReadFull(rand.Reader, id128)
+	id128[8] = id128[8]&^0xc0 | 0x80
+	id128[6] = id128[6]&^0xf0 | 0x40
+	uuid := fmt.Sprintf("%x-%x-%x-%x-%x", id128[0:4], id128[4:6], id128[6:8], id128[8:10], id128[10:])
+
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+
+	// Garbage-collect old clients
+	for key, client := range t.clients {
+		if time.Since(client.time).Minutes() > 1 {
+			delete(t.clients, key)
+		}
+	}
+
+	if len(t.clients) > 100 {
+		return nil
+	}
+
+	c := client{
+		id:   uuid,
+		time: time.Now(),
+	}
+	t.clients[uuid] = &c
+
+	return &c
+}
+
+func (t *test) RemoveClient(id string) {
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+
+	delete(t.clients, id)
+}
+
+func (t *test) Start(c orgvarlinkcertification.VarlinkCall) error {
+	return c.ReplyStart(t.NewClient().id)
+}
+
+func (t *test) Test01(c orgvarlinkcertification.VarlinkCall, client_id_ string) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	return c.ReplyTest01(true)
+}
+
+func (t *test) Test02(c orgvarlinkcertification.VarlinkCall, client_id_ string, bool_ bool) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if !bool_ {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	return c.ReplyTest02(1)
+}
+
+func (t *test) Test03(c orgvarlinkcertification.VarlinkCall, client_id_ string, int_ int64) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if int_ != 1 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	return c.ReplyTest03(1.0)
+}
+
+func (t *test) Test04(c orgvarlinkcertification.VarlinkCall, client_id_ string, float_ float64) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if float_ != 1.0 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	return c.ReplyTest04("ping")
+}
+func (t *test) Test05(c orgvarlinkcertification.VarlinkCall, client_id_ string, string_ string) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if string_ != "ping" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	return c.ReplyTest05(false, 2, math.Pi, "a lot of string")
+}
+
+func (t *test) Test06(c orgvarlinkcertification.VarlinkCall, client_id_ string, bool_ bool, int_ int64, float_ float64, string_ string) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if bool_ {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if int_ != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if float_ != math.Pi {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if string_ != "a lot of string" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	s := struct {
+		Bool   bool
+		Int    int64
+		Float  float64
+		String string
+	}{
+		Bool:   false,
+		Int:    2,
+		Float:  math.Pi,
+		String: "a lot of string",
+	}
+	return c.ReplyTest06(s)
+}
+
+func (t *test) Test07(c orgvarlinkcertification.VarlinkCall, client_id_ string, struct_ struct {
+	Bool   bool
+	Int    int64
+	Float  float64
+	String string
+}) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if struct_.Bool {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if struct_.Int != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if struct_.Float != math.Pi {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if struct_.String != "a lot of string" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	m := map[string]string{
+		"bar": "Bar",
+		"foo": "Foo",
+	}
+	return c.ReplyTest07(m)
+}
+
+func (t *test) Test08(c orgvarlinkcertification.VarlinkCall, client_id_ string, map_ map[string]string) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if len(map_) != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if map_["bar"] != "Bar" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if map_["foo"] != "Foo" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	m := map[string]struct{}{
+		"one":   {},
+		"two":   {},
+		"three": {},
+	}
+	return c.ReplyTest08(m)
+}
+
+func (t *test) Test09(c orgvarlinkcertification.VarlinkCall, client_id_ string, set_ map[string]struct{}) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if len(set_) != 3 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	_, ok := set_["one"]
+	if !ok {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	_, ok = set_["two"]
+	if !ok {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	_, ok = set_["three"]
+	if !ok {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	m := orgvarlinkcertification.MyType{
+		Object: json.RawMessage(`{"method": "org.varlink.certification.Test09", "parameters": {"map": {"foo": "Foo", "bar": "Bar"}}}`),
+		Enum:   "two",
+		Struct: struct {
+			First  int64  `json:"first"`
+			Second string `json:"second"`
+		}{First: 1, Second: "2"},
+		Array:                 []string{"one", "two", "three"},
+		Dictionary:            map[string]string{"foo": "Foo", "bar": "Bar"},
+		Stringset:             map[string]struct{}{"one": {}, "two": {}, "three": {}},
+		Nullable:              nil,
+		Nullable_array_struct: nil,
+		Interface: orgvarlinkcertification.Interface{
+			Foo: &[]*map[string]string{
+				nil,
+				&map[string]string{"Foo": "foo", "Bar": "bar"},
+				nil,
+				&map[string]string{"one": "foo", "two": "bar"},
+			},
+			Anon: struct {
+				Foo bool `json:"foo"`
+				Bar bool `json:"bar"`
+			}{Foo: true, Bar: false},
+		},
+	}
+	return c.ReplyTest09(m)
+}
+
+func (t *test) Test10(c orgvarlinkcertification.VarlinkCall, client_id_ string, mytype_ orgvarlinkcertification.MyType) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	var o struct {
+		Method     string `json:"method"`
+		Parameters struct {
+			Map map[string]string `json:"map"`
+		} `json:"parameters"`
+	}
+	err := json.Unmarshal(mytype_.Object, &o)
+	if err != nil {
+		return err
+	}
+
+	if o.Method != "org.varlink.certification.Test09" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if len(o.Parameters.Map) != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if o.Parameters.Map["bar"] != "Bar" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if o.Parameters.Map["foo"] != "Foo" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Enum != "two" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Struct.First != 1 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Struct.Second != "2" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if len(mytype_.Array) != 3 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Array[0] != "one" && mytype_.Array[1] != "two" && mytype_.Array[2] != "three" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if len(mytype_.Dictionary) != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Dictionary["bar"] != "Bar" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Dictionary["foo"] != "Foo" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if len(mytype_.Stringset) != 3 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	_, ok := mytype_.Stringset["one"]
+	if !ok {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	_, ok = mytype_.Stringset["two"]
+	if !ok {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	_, ok = mytype_.Stringset["three"]
+	if !ok {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Nullable != nil {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Nullable_array_struct != nil {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	i := *mytype_.Interface.Foo
+	if len(i) != 4 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if i[0] != nil {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if len(*i[1]) != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if (*i[1])["Foo"] != "foo" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if (*i[1])["Bar"] != "bar" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if i[2] != nil {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if len(*i[3]) != 2 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if (*i[3])["one"] != "foo" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if (*i[3])["two"] != "bar" {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if !mytype_.Interface.Anon.Foo {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if mytype_.Interface.Anon.Bar {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if !c.WantsMore() {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	for i := 1; i <= 10; i++ {
+		c.Continues = i < 10
+		err := c.ReplyTest10("Reply number " + strconv.Itoa(i))
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (t *test) Test11(c orgvarlinkcertification.VarlinkCall, client_id_ string, last_more_replies_ []string) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	if len(last_more_replies_) != 10 {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	if !c.IsOneway() {
+		return c.ReplyCertificationError(nil, nil)
+	}
+
+	for i := 1; i <= 10; i++ {
+		if last_more_replies_[i] != "Reply number "+strconv.Itoa(i) {
+			return c.ReplyCertificationError(nil, nil)
+		}
+	}
+
+	return c.ReplyTest11()
+}
+
+func (t *test) End(c orgvarlinkcertification.VarlinkCall, client_id_ string) error {
+	if t.Client(client_id_) == nil {
+		return c.ReplyClientIdError()
+	}
+
+	t.RemoveClient(client_id_)
+	return c.ReplyEnd(true)
+}
+
+func run_server(address string) {
+	t := test{
+		clients: make(map[string]*client),
+	}
+
+	s, err := varlink.NewService(
+		"Varlink",
+		"Certification",
+		"1",
+		"https://github.com/varlink/go",
+	)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+
+	s.RegisterInterface(orgvarlinkcertification.VarlinkNew(&t))
+	err = s.Listen(address, 0)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
+
+func main() {
+	var address string
+	var client bool
+
+	flag.StringVar(&address, "varlink", "", "Varlink address")
+	flag.BoolVar(&client, "client", false, "Run as client")
+	flag.Parse()
+
+	if address == "" {
+		flag.Usage()
+		os.Exit(1)
+	}
+
+	if client {
+		run_client(address)
+		return
+	}
+
+	run_server(address)
+}

vendor/github.com/varlink/go/cmd/varlink-go-certification/orgvarlinkcertification/generate.go

@@ -0,0 +1,3 @@
+package orgvarlinkcertification
+
+//go:generate go run ../../varlink-go-interface-generator/main.go org.varlink.certification.varlink

vendor/github.com/varlink/go/cmd/varlink-go-certification/orgvarlinkcertification/org.varlink.certification.varlink

@@ -0,0 +1,89 @@
+# Interface to test varlink implementations against.
+# First you write a varlink client calling:
+# Start, Test01, Test02, …, Test09, End
+# The return value of the previous call should be the argument of the next call.
+# Then you test this client against well known servers like python or rust from
+# https://github.com/varlink/
+#
+# Next you write a varlink server providing the same service as the well known ones.
+# Now run your client against it and run well known clients like python or rust
+# from https://github.com/varlink/ against your server. If all works out, then
+# your new language bindings should be varlink certified.
+interface org.varlink.certification
+
+type Interface (
+  foo: ?[]?[string](foo, bar, baz),
+  anon: (foo: bool, bar: bool)
+)
+
+type MyType (
+  object: object,
+  enum: (one, two, three),
+  struct: (first: int, second: string),
+  array: []string,
+  dictionary: [string]string,
+  stringset: [string](),
+  nullable: ?string,
+  nullable_array_struct: ?[](first: int, second: string),
+  interface: Interface
+)
+
+method Start() -> (client_id: string)
+
+method Test01(client_id: string) -> (bool: bool)
+
+method Test02(client_id: string, bool: bool) -> (int: int)
+
+method Test03(client_id: string, int: int) -> (float: float)
+
+method Test04(client_id: string, float: float) -> (string: string)
+
+method Test05(client_id: string, string: string) -> (
+  bool: bool,
+  int: int,
+  float: float,
+  string: string
+)
+
+method Test06(
+  client_id: string,
+  bool: bool,
+  int: int,
+  float: float,
+  string: string
+) -> (
+  struct: (
+    bool: bool,
+    int: int,
+    float: float,
+    string: string
+  )
+)
+
+method Test07(
+  client_id: string,
+  struct: (
+    bool: bool,
+    int: int,
+    float: float,
+    string: string
+  )
+) -> (map: [string]string)
+
+method Test08(client_id: string, map: [string]string) -> (set: [string]())
+
+method Test09(client_id: string, set: [string]()) -> (mytype: MyType)
+
+# returns more than one reply with "continues"
+method Test10(client_id: string, mytype: MyType) -> (string: string)
+
+method Test11(
+  client_id: string,
+  last_more_replies: []string
+) -> ()
+
+method End(client_id: string) -> (all_ok: bool)
+
+error ClientIdError ()
+
+error CertificationError (wants: object, got: object)

vendor/github.com/varlink/go/cmd/varlink-go-interface-generator/main.go

@@ -95,14 +95,51 @@ func generateTemplate(description string) (string, []byte, error) {
 		b.WriteString("\n\n")
 	}
 
-	b.WriteString("// Client method calls and reply readers\n")
+	b.WriteString("// Client method calls\n")
 	for _, m := range midl.Methods {
-		b.WriteString("func " + m.Name + "(c__ *varlink.Connection, more__ bool, oneway__ bool")
+		b.WriteString("type " + m.Name + "_methods struct{}\n")
+		b.WriteString("func " + m.Name + "() " + m.Name + "_methods { return " + m.Name + "_methods{} }\n\n")
+
+		b.WriteString("func (m " + m.Name + "_methods) Call(c *varlink.Connection")
 		for _, field := range m.In.Fields {
-			b.WriteString(", " + field.Name + "_ ")
+			b.WriteString(", " + field.Name + "_in_ ")
 			writeType(&b, field.Type, false, 1)
 		}
-		b.WriteString(") error {\n")
+		b.WriteString(") (")
+		for _, field := range m.Out.Fields {
+			b.WriteString(field.Name + "_out_ ")
+			writeType(&b, field.Type, false, 1)
+			b.WriteString(", ")
+		}
+		b.WriteString("err_ error) {\n")
+		b.WriteString("receive, err_ := m.Send(c, 0")
+		for _, field := range m.In.Fields {
+			b.WriteString(", " + field.Name + "_in_ ")
+		}
+		b.WriteString(")\n")
+		b.WriteString("if err_ != nil {\n" +
+			"\treturn\n" +
+			"}\n")
+		b.WriteString("\t")
+		for _, field := range m.Out.Fields {
+			b.WriteString(field.Name + "_out_ ")
+			b.WriteString(", ")
+		}
+		b.WriteString("_, err_ = receive()\n")
+		b.WriteString("\treturn\n" +
+			"}\n\n")
+
+		b.WriteString("func (m " + m.Name + "_methods) Send(c *varlink.Connection, flags uint64")
+		for _, field := range m.In.Fields {
+			b.WriteString(", " + field.Name + "_in_ ")
+			writeType(&b, field.Type, false, 1)
+		}
+		b.WriteString(") (func() (")
+		for _, field := range m.Out.Fields {
+			writeType(&b, field.Type, false, 1)
+			b.WriteString(", ")
+		}
+		b.WriteString("uint64, error), error) {\n")
 		if len(m.In.Fields) > 0 {
 			b.WriteString("\tvar in ")
 			writeType(&b, m.In, true, 1)
@@ -112,58 +149,57 @@ func generateTemplate(description string) (string, []byte, error) {
 				case idl.TypeStruct, idl.TypeArray, idl.TypeMap:
 					b.WriteString("\tin." + strings.Title(field.Name) + " = ")
 					writeType(&b, field.Type, true, 1)
-					b.WriteString("(" + field.Name + "_)\n")
+					b.WriteString("(" + field.Name + "_in_)\n")
 
 				default:
-					b.WriteString("\tin." + strings.Title(field.Name) + " = " + field.Name + "_\n")
+					b.WriteString("\tin." + strings.Title(field.Name) + " = " + field.Name + "_in_\n")
 				}
 			}
-			b.WriteString("\treturn c__.Send(\"" + midl.Name + "." + m.Name + "\", in, more__, oneway__)\n" +
-				"}\n\n")
+			b.WriteString("\treceive, err := c.Send(\"" + midl.Name + "." + m.Name + "\", in, flags)\n")
 		} else {
-			b.WriteString("\treturn c__.Send(\"" + midl.Name + "." + m.Name + "\", nil, more__, oneway__)\n" +
-				"}\n\n")
+			b.WriteString("\treceive, err := c.Send(\"" + midl.Name + "." + m.Name + "\", nil, flags)\n")
 		}
-
-		b.WriteString("func Read" + m.Name + "_(c__ *varlink.Connection")
+		b.WriteString("if err != nil {\n" +
+			"\treturn nil, err\n" +
+			"}\n")
+		b.WriteString("\treturn func() (")
 		for _, field := range m.Out.Fields {
-			b.WriteString(", " + field.Name + "_ *")
-			writeType(&b, field.Type, false, 1)
+			b.WriteString(field.Name + "_out_ ")
+			writeType(&b, field.Type, false, 3)
+			b.WriteString(", ")
 		}
-		b.WriteString(") (bool, error) {\n")
+		b.WriteString("flags uint64, err error) {\n")
 		if len(m.Out.Fields) > 0 {
-			b.WriteString("\tvar out ")
-			writeType(&b, m.Out, true, 1)
+			b.WriteString("\t\tvar out ")
+			writeType(&b, m.Out, true, 2)
 			b.WriteString("\n")
-			b.WriteString("\tcontinues_, err := c__.Receive(&out)\n")
+			b.WriteString("\t\tflags, err = receive(&out)\n")
 		} else {
-			b.WriteString("\tcontinues_, err := c__.Receive(nil)\n")
+			b.WriteString("\t\tflags, err = receive(nil)\n")
 		}
-		b.WriteString("\tif err != nil {\n" +
-			"\t\treturn false, err\n" +
-			"\t}\n")
+		b.WriteString("\t\tif err != nil {\n" +
+			"\t\t\treturn\n" +
+			"\t\t}\n")
 		for _, field := range m.Out.Fields {
-			b.WriteString("\tif " + field.Name + "_ != nil {\n")
+			b.WriteString("\t\t" + field.Name + "_out_ = ")
 			switch field.Type.Kind {
 			case idl.TypeStruct, idl.TypeArray, idl.TypeMap:
-				b.WriteString("\t\t*" + field.Name + "_ = ")
 				writeType(&b, field.Type, false, 2)
-				b.WriteString(" (out." + strings.Title(field.Name) + ")\n")
+				b.WriteString("(out." + strings.Title(field.Name) + ")\n")
 
 			default:
-				b.WriteString("\t\t*" + field.Name + "_ = out." + strings.Title(field.Name) + "\n")
+				b.WriteString("out." + strings.Title(field.Name) + "\n")
 			}
-			b.WriteString("\t}\n")
 		}
-
-		b.WriteString("\treturn continues_, nil\n" +
-			"}\n\n")
+		b.WriteString("\t\treturn\n" +
+			"\t}, nil\n")
+		b.WriteString("}\n\n")
 	}
 
 	b.WriteString("// Service interface with all methods\n")
 	b.WriteString("type " + pkgname + "Interface interface {\n")
 	for _, m := range midl.Methods {
-		b.WriteString("\t" + m.Name + "(c__ VarlinkCall")
+		b.WriteString("\t" + m.Name + "(c VarlinkCall")
 		for _, field := range m.In.Fields {
 			b.WriteString(", " + field.Name + "_ ")
 			writeType(&b, field.Type, false, 1)
@@ -177,7 +213,7 @@ func generateTemplate(description string) (string, []byte, error) {
 
 	b.WriteString("// Reply methods for all varlink errors\n")
 	for _, e := range midl.Errors {
-		b.WriteString("func (c__ *VarlinkCall) Reply" + e.Name + "(")
+		b.WriteString("func (c *VarlinkCall) Reply" + e.Name + "(")
 		for i, field := range e.Type.Fields {
 			if i > 0 {
 				b.WriteString(", ")
@@ -201,16 +237,16 @@ func generateTemplate(description string) (string, []byte, error) {
 					b.WriteString("\tout." + strings.Title(field.Name) + " = " + field.Name + "_\n")
 				}
 			}
-			b.WriteString("\treturn c__.ReplyError(\"" + midl.Name + "." + e.Name + "\", &out)\n")
+			b.WriteString("\treturn c.ReplyError(\"" + midl.Name + "." + e.Name + "\", &out)\n")
 		} else {
-			b.WriteString("\treturn c__.ReplyError(\"" + midl.Name + "." + e.Name + "\", nil)\n")
+			b.WriteString("\treturn c.ReplyError(\"" + midl.Name + "." + e.Name + "\", nil)\n")
 		}
 		b.WriteString("}\n\n")
 	}
 
 	b.WriteString("// Reply methods for all varlink methods\n")
 	for _, m := range midl.Methods {
-		b.WriteString("func (c__ *VarlinkCall) Reply" + m.Name + "(")
+		b.WriteString("func (c *VarlinkCall) Reply" + m.Name + "(")
 		for i, field := range m.Out.Fields {
 			if i > 0 {
 				b.WriteString(", ")
@@ -234,27 +270,27 @@ func generateTemplate(description string) (string, []byte, error) {
 					b.WriteString("\tout." + strings.Title(field.Name) + " = " + field.Name + "_\n")
 				}
 			}
-			b.WriteString("\treturn c__.Reply(&out)\n")
+			b.WriteString("\treturn c.Reply(&out)\n")
 		} else {
-			b.WriteString("\treturn c__.Reply(nil)\n")
+			b.WriteString("\treturn c.Reply(nil)\n")
 		}
 		b.WriteString("}\n\n")
 	}
 
-	b.WriteString("// Dummy methods for all varlink methods\n")
+	b.WriteString("// Dummy implementations for all varlink methods\n")
 	for _, m := range midl.Methods {
-		b.WriteString("func (s__ *VarlinkInterface) " + m.Name + "(c__ VarlinkCall")
+		b.WriteString("func (s *VarlinkInterface) " + m.Name + "(c VarlinkCall")
 		for _, field := range m.In.Fields {
 			b.WriteString(", " + field.Name + "_ ")
 			writeType(&b, field.Type, false, 1)
 		}
 		b.WriteString(") error {\n" +
-			"\treturn c__.ReplyMethodNotImplemented(\"" + m.Name + "\")\n" +
+			"\treturn c.ReplyMethodNotImplemented(\"" + midl.Name + "." + m.Name + "\")\n" +
 			"}\n\n")
 	}
 
 	b.WriteString("// Method call dispatcher\n")
-	b.WriteString("func (s__ *VarlinkInterface) VarlinkDispatch(call varlink.Call, methodname string) error {\n" +
+	b.WriteString("func (s *VarlinkInterface) VarlinkDispatch(call varlink.Call, methodname string) error {\n" +
 		"\tswitch methodname {\n")
 	for _, m := range midl.Methods {
 		b.WriteString("\tcase \"" + m.Name + "\":\n")
@@ -266,7 +302,7 @@ func generateTemplate(description string) (string, []byte, error) {
 				"\t\tif err != nil {\n" +
 				"\t\t\treturn call.ReplyInvalidParameter(\"parameters\")\n" +
 				"\t\t}\n")
-			b.WriteString("\t\treturn s__." + pkgname + "Interface." + m.Name + "(VarlinkCall{call}")
+			b.WriteString("\t\treturn s." + pkgname + "Interface." + m.Name + "(VarlinkCall{call}")
 			if len(m.In.Fields) > 0 {
 				for _, field := range m.In.Fields {
 					switch field.Type.Kind {
@@ -282,7 +318,7 @@ func generateTemplate(description string) (string, []byte, error) {
 			}
 			b.WriteString(")\n")
 		} else {
-			b.WriteString("\t\treturn s__." + pkgname + "Interface." + m.Name + "(VarlinkCall{call})\n")
+			b.WriteString("\t\treturn s." + pkgname + "Interface." + m.Name + "(VarlinkCall{call})\n")
 		}
 		b.WriteString("\n")
 	}
@@ -292,11 +328,11 @@ func generateTemplate(description string) (string, []byte, error) {
 		"}\n\n")
 
 	b.WriteString("// Varlink interface name\n")
-	b.WriteString("func (s__ *VarlinkInterface) VarlinkGetName() string {\n" +
+	b.WriteString("func (s *VarlinkInterface) VarlinkGetName() string {\n" +
 		"\treturn `" + midl.Name + "`\n" + "}\n\n")
 
 	b.WriteString("// Varlink interface description\n")
-	b.WriteString("func (s__ *VarlinkInterface) VarlinkGetDescription() string {\n" +
+	b.WriteString("func (s *VarlinkInterface) VarlinkGetDescription() string {\n" +
 		"\treturn `" + midl.Description + "\n`\n}\n\n")
 
 	b.WriteString("// Service interface\n")

vendor/github.com/varlink/go/varlink/call.go

@@ -21,9 +21,9 @@ func (c *Call) WantsMore() bool {
 	return c.in.More
 }
 
-// IsOneShot indicate that the calling client does not expect a reply.
-func (c *Call) IsOneShot() bool {
-	return c.in.OneShot
+// IsOneway indicate that the calling client does not expect a reply.
+func (c *Call) IsOneway() bool {
+	return c.in.Oneway
 }
 
 // GetParameters retrieves the method call parameters.
@@ -35,7 +35,7 @@ func (c *Call) GetParameters(p interface{}) error {
 }
 
 func (c *Call) sendMessage(r *serviceReply) error {
-	if c.in.OneShot {
+	if c.in.Oneway {
 		return nil
 	}
 

vendor/github.com/varlink/go/varlink/connection.go

@@ -7,6 +7,15 @@ import (
 	"strings"
 )
 
+// Message flags for Send(). More indicates that the client accepts more than one method
+// reply to this call. Oneway requests, that the service must not send a method reply to
+// this call. Continues indicates that the service will send more than one reply.
+const (
+	More      = 1 << iota
+	Oneway    = 1 << iota
+	Continues = 1 << iota
+)
+
 // Error is a varlink error returned from a method call.
 type Error struct {
 	Name       string
@@ -26,8 +35,10 @@ type Connection struct {
 	writer  *bufio.Writer
 }
 
-// Send sends a method call.
-func (c *Connection) Send(method string, parameters interface{}, more bool, oneway bool) error {
+// Send sends a method call. It returns a receive() function which is called to retrieve the method reply.
+// If Send() is called with the `More`flag and the receive() function carries the `Continues` flag, receive()
+// can be called multiple times to retrieve multiple replies.
+func (c *Connection) Send(method string, parameters interface{}, flags uint64) (func(interface{}) (uint64, error), error) {
 	type call struct {
 		Method     string      `json:"method"`
 		Parameters interface{} `json:"parameters,omitempty"`
@@ -35,8 +46,8 @@ func (c *Connection) Send(method string, parameters interface{}, more bool, onew
 		Oneway     bool        `json:"oneway,omitempty"`
 	}
 
-	if more && oneway {
-		return &Error{
+	if (flags&More != 0) && (flags&Oneway != 0) {
+		return nil, &Error{
 			Name:       "org.varlink.InvalidParameter",
 			Parameters: "oneway",
 		}
@@ -45,64 +56,73 @@ func (c *Connection) Send(method string, parameters interface{}, more bool, onew
 	m := call{
 		Method:     method,
 		Parameters: parameters,
-		More:       more,
-		Oneway:     oneway,
+		More:       flags&More != 0,
+		Oneway:     flags&Oneway != 0,
 	}
 	b, err := json.Marshal(m)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
 	b = append(b, 0)
 	_, err = c.writer.Write(b)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
-	return c.writer.Flush()
-}
-
-// Receive receives a method reply.
-func (c *Connection) Receive(parameters interface{}) (bool, error) {
-	type reply struct {
-		Parameters *json.RawMessage `json:"parameters"`
-		Continues  bool             `json:"continues"`
-		Error      string           `json:"error"`
-	}
-
-	out, err := c.reader.ReadBytes('\x00')
+	err = c.writer.Flush()
 	if err != nil {
-		return false, err
+		return nil, err
 	}
 
-	var m reply
-	err = json.Unmarshal(out[:len(out)-1], &m)
-	if err != nil {
-		return false, err
-	}
-
-	if m.Error != "" {
-		return false, &Error{
-			Name:       m.Error,
-			Parameters: m.Parameters,
+	receive := func(out_parameters interface{}) (uint64, error) {
+		type reply struct {
+			Parameters *json.RawMessage `json:"parameters"`
+			Continues  bool             `json:"continues"`
+			Error      string           `json:"error"`
 		}
+
+		out, err := c.reader.ReadBytes('\x00')
+		if err != nil {
+			return 0, err
+		}
+
+		var m reply
+		err = json.Unmarshal(out[:len(out)-1], &m)
+		if err != nil {
+			return 0, err
+		}
+
+		if m.Error != "" {
+			err = &Error{
+				Name:       m.Error,
+				Parameters: m.Parameters,
+			}
+			return 0, err
+		}
+
+		if m.Parameters != nil {
+			json.Unmarshal(*m.Parameters, out_parameters)
+		}
+
+		if m.Continues {
+			return Continues, nil
+		}
+
+		return 0, nil
 	}
 
-	if parameters != nil && m.Parameters != nil {
-		return m.Continues, json.Unmarshal(*m.Parameters, parameters)
-	}
-
-	return m.Continues, nil
+	return receive, nil
 }
 
-// Call sends a method call and returns the result of the call.
-func (c *Connection) Call(method string, parameters interface{}, result interface{}) error {
-	err := c.Send(method, &parameters, false, false)
+// Call sends a method call and returns the method reply.
+func (c *Connection) Call(method string, parameters interface{}, out_parameters interface{}) error {
+	receive, err := c.Send(method, &parameters, 0)
 	if err != nil {
 		return err
 	}
 
-	_, err = c.Receive(result)
+	_, err = receive(out_parameters)
 	return err
 }
 

vendor/github.com/varlink/go/varlink/idl/idl.go

@@ -58,6 +58,7 @@ type Method struct {
 // Error represents an error defined in the interface description.
 type Error struct {
 	Name string
+	Doc  string
 	Type *Type
 }
 
@@ -393,6 +394,7 @@ func (p *parser) readError(idl *IDL) (*Error, error) {
 	e := &Error{}
 
 	p.advance()
+	e.Doc = p.lastComment.String()
 	e.Name = p.readTypeName()
 	if e.Name == "" {
 		return nil, fmt.Errorf("missing error name")

vendor/github.com/varlink/go/varlink/service.go

@@ -23,7 +23,7 @@ type serviceCall struct {
 	Method     string           `json:"method"`
 	Parameters *json.RawMessage `json:"parameters,omitempty"`
 	More       bool             `json:"more,omitempty"`
-	OneShot    bool             `json:"oneshot,omitempty"`
+	Oneway     bool             `json:"oneway,omitempty"`
 }
 
 type serviceReply struct {

vendor/github.com/varlink/go/varlink/varlink_test.go

@@ -140,7 +140,7 @@ func (s *VarlinkInterface) VarlinkDispatch(call Call, methodname string) error {
 		if !call.WantsMore() {
 			return fmt.Errorf("More flag not passed")
 		}
-		if call.IsOneShot() {
+		if call.IsOneway() {
 			return fmt.Errorf("OneShot flag set")
 		}
 		call.Continues = true