Rename v2 to v2alpha.

Any incremental development on this should be clearly labeled as
unstable.

v2alpha/soap/envelope/envelope.go

@@ -0,0 +1,141 @@
+// Package envelope is responsible for encoding and decoding SOAP envelopes.
+package envelope
+
+import (
+	"encoding/xml"
+	"fmt"
+	"io"
+)
+
+// FaultDetail carries XML-encoded application-specific Fault details.
+type FaultDetail struct {
+	Raw []byte `xml:",innerxml"`
+}
+
+// Fault implements error, and contains SOAP fault information.
+type Fault struct {
+	Code   string      `xml:"faultcode"`
+	String string      `xml:"faultstring"`
+	Actor  string      `xml:"faultactor"`
+	Detail FaultDetail `xml:"detail"`
+}
+
+func (fe *Fault) Error() string {
+	return fmt.Sprintf("SOAP fault code=%s: %s", fe.Code, fe.String)
+}
+
+// Various "constant" bytes used in the written envelope.
+var (
+	envOpen  = []byte(xml.Header + `<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><s:Body>`)
+	env1     = []byte(`<u:`)
+	env2     = []byte(` xmlns:u="`)
+	env3     = []byte(`">`)
+	env4     = []byte(`</u:`)
+	env5     = []byte(`>`)
+	envClose = []byte(`</s:Body></s:Envelope>`)
+)
+
+// Action wraps a SOAP action to be read or written as part of a SOAP envelope.
+type Action struct {
+	// XMLName specifies the XML element namespace (URI) and name. Together
+	// these identify the SOAP action.
+	XMLName xml.Name
+	// Args is an arbitrary struct containing fields for encoding or decoding
+	// arguments. See https://pkg.go.dev/encoding/xml@go1.17.1#Marshal and
+	// https://pkg.go.dev/encoding/xml@go1.17.1#Unmarshal for details on
+	// annotating fields in the structure.
+	Args interface{} `xml:",any"`
+}
+
+// Write marshals a SOAP envelope to the writer. Errors can be from the writer
+// or XML encoding.
+func Write(w io.Writer, action *Action) error {
+	// Experiments with one router have shown that it 500s for requests where
+	// the outer default xmlns is set to the SOAP namespace, and then
+	// reassigning the default namespace within that to the service namespace.
+	// Most of the code in this function is hand-coding the outer XML to
+	// workaround this.
+	// Resolving https://github.com/golang/go/issues/9519 might remove the need
+	// for this workaround.
+
+	_, err := w.Write(envOpen)
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(env1)
+	if err != nil {
+		return err
+	}
+	err = xml.EscapeText(w, []byte(action.XMLName.Local))
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(env2)
+	if err != nil {
+		return err
+	}
+	err = xml.EscapeText(w, []byte(action.XMLName.Space))
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(env3)
+	if err != nil {
+		return err
+	}
+	enc := xml.NewEncoder(w)
+	err = enc.Encode(action.Args)
+	if err != nil {
+		return err
+	}
+	err = enc.Flush()
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(env4)
+	if err != nil {
+		return err
+	}
+	xml.EscapeText(w, []byte(action.XMLName.Local))
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(env5)
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(envClose)
+	return err
+}
+
+// Read unmarshals a SOAP envelope from the reader. Errors can either be from
+// the reader, XML decoding, or a *Fault.
+func Read(r io.Reader, action *Action) error {
+	env := envelope{
+		Body: body{
+			Action: action,
+		},
+	}
+
+	dec := xml.NewDecoder(r)
+	err := dec.Decode(&env)
+	if err != nil {
+		return err
+	}
+
+	if env.Body.Fault != nil {
+		return env.Body.Fault
+	}
+
+	return nil
+}
+
+type envelope struct {
+	XMLName       xml.Name `xml:"http://schemas.xmlsoap.org/soap/envelope/ Envelope"`
+	EncodingStyle string   `xml:"http://schemas.xmlsoap.org/soap/envelope/ encodingStyle,attr"`
+	Body          body     `xml:"http://schemas.xmlsoap.org/soap/envelope/ Body"`
+}
+
+type body struct {
+	Fault  *Fault  `xml:"Fault"`
+	Action *Action `xml:",any"`
+}

v2alpha/soap/envelope/envelope_test.go

@@ -0,0 +1,78 @@
+package envelope
+
+import (
+	"bytes"
+	"encoding/xml"
+	"reflect"
+	"testing"
+)
+
+func TestWriteRead(t *testing.T) {
+	type Args struct {
+		Foo string `xml:"foo"`
+		Bar string `xml:"bar"`
+	}
+
+	sendAction := &Action{
+		XMLName: xml.Name{Space: "http://example.com/namespace", Local: "MyAction"},
+		Args: &Args{
+			Foo: "foo-1",
+			Bar: "bar-2",
+		},
+	}
+
+	buf := &bytes.Buffer{}
+	err := Write(buf, sendAction)
+	if err != nil {
+		t.Errorf("Write want success, got err=%v", err)
+	}
+
+	recvAction := &Action{Args: &Args{}}
+
+	err = Read(buf, recvAction)
+	if err != nil {
+		t.Errorf("Read want success, got err=%v", err)
+	}
+
+	if !reflect.DeepEqual(sendAction, recvAction) {
+		t.Errorf("want recvAction=%+v, got %+v", sendAction, recvAction)
+	}
+}
+
+func TestReadFault(t *testing.T) {
+	env := []byte(xml.Header + `
+<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
+s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
+<s:Body>
+<s:Fault>
+<faultcode>dummy code</faultcode>
+<faultstring>dummy string</faultstring>
+<faultactor>dummy actor</faultactor>
+<detail>dummy detail</detail>
+</s:Fault>
+</s:Body>
+</s:Envelope>
+`)
+
+	type args struct{}
+
+	err := Read(bytes.NewBuffer(env), &Action{Args: &args{}})
+	if err == nil {
+		t.Fatal("want err != nil, got nil")
+	}
+
+	gotFault, ok := err.(*Fault)
+	if !ok {
+		t.Fatalf("want *Fault, got %T", err)
+	}
+
+	wantFault := &Fault{
+		Code:   "dummy code",
+		String: "dummy string",
+		Actor:  "dummy actor",
+		Detail: FaultDetail{Raw: []byte("dummy detail")},
+	}
+	if !reflect.DeepEqual(wantFault, gotFault) {
+		t.Errorf("want %+v, got %+v", wantFault, gotFault)
+	}
+}