gowsdl

package module
v0.0.0-...-e384898 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2025 License: MPL-2.0 Imports: 11 Imported by: 0

README

WSDL to Go

Gitter GoDoc Build Status codecov Go Report Card

Generates idiomatic Go code from WSDL files with support for WSDL 1.1, WSDL 2.0, and modern Go features including generics.

Requirements
  • Go 1.21 or higher
Install
  • Download release
  • Download and build locally
    • Go 1.21+: go install github.com/enthus-golang/gowsdl/cmd/gowsdl@latest
  • Install from Homebrew: brew install gowsdl
Goals
  • Generate idiomatic Go code as much as possible
  • Support only Document/Literal wrapped services, which are WS-I compliant
  • Support:
    • WSDL 1.1 and WSDL 2.0
    • XML Schema 1.0
    • SOAP 1.1
  • Resolve external XML Schemas
  • Support external and local WSDL
  • Full namespace handling and preservation
  • XSD element reference resolution
Caveats
  • Please keep in mind that the generated code is just a reflection of what the WSDL is like. If your WSDL has duplicated type definitions, your Go code is going to have the same and may not compile.
Usage
Usage: gowsdl [options] myservice.wsdl
  -o string
        File where the generated code will be saved (default "myservice.go")
  -p string
        Package under which code will be generated (default "myservice")
  -i    Skips TLS Verification
  -v    Shows gowsdl version
  -use-generics
        Generate code using Go generics (requires Go 1.18+ for generic features)
  -insecure-skip-verify
        Skip TLS certificate verification when downloading WSDLs
  -ca-cert string
        Path to CA certificate file for TLS verification
  -tls-cert string
        Path to client certificate for mutual TLS
  -tls-key string
        Path to client key for mutual TLS
  -proxy string
        HTTP proxy URL
  -timeout duration
        HTTP client timeout (default 30s)
  -server
        Generate server-side code in addition to client code
Go Generics Support

Starting with Go 1.18, gowsdl can generate code that uses generics for type-safe SOAP operations. This feature provides:

  • Type-safe SOAP clients with compile-time type checking
  • Generic result types that can handle both success responses and SOAP faults
  • Generic array types for better handling of unbounded elements
  • Backward compatibility with non-generic code generation

To enable generic code generation, use the -use-generics flag:

gowsdl -use-generics -p myservice -o myservice.go myservice.wsdl
Example Usage

With generics enabled, you get additional methods for each operation:

// Standard interface (always generated)
response, err := client.GetUser(&GetUserRequest{UserID: 123})
if err != nil {
    // Handle error
}

// Generic interface (only with -use-generics flag)
result, err := client.GetUserGeneric(&GetUserRequest{UserID: 123})
if err != nil {
    // Handle transport error
}

if result.IsSuccess() {
    user, _ := result.Unwrap()
    // Use user
} else {
    // Handle SOAP fault
    if result.TransportError {
        // Network/transport error (connection refused, timeout, etc.)
        fmt.Printf("Transport Error: %s\n", result.Fault.String)
    } else {
        // Business logic error from SOAP service
        fmt.Printf("SOAP Fault: %s\n", result.Fault.String)
    }
}

The generic interface provides better type safety and explicit fault handling, making it easier to distinguish between transport errors and business logic errors (SOAP faults).

New Features
WSDL 2.0 Support

gowsdl now fully supports both WSDL 1.1 and WSDL 2.0 documents with complete code generation capabilities. Features include:

  • Automatic version detection - WSDL version is detected from the root element namespace
  • Complete parsing support for WSDL 2.0 structures:
    • Interface definitions (replacing portType from WSDL 1.1)
    • Endpoint definitions (replacing port from WSDL 1.1)
    • Modern message exchange patterns
    • Enhanced fault handling with input/output fault references
  • Full code generation - Operations, types, and server code are generated using WSDL 2.0-specific templates
  • Backward compatibility - All existing WSDL 1.1 functionality remains unchanged

Example usage with WSDL 2.0 files:

# Works seamlessly with both WSDL 1.1 and 2.0
gowsdl -p myservice -o myservice.go https://example.com/service.wsdl
Enhanced Namespace Handling

Namespaces are now properly preserved and managed throughout the code generation process:

  • XML namespace prefixes are maintained in generated code
  • Namespace collisions are automatically resolved
  • Generated XML tags include proper namespace information
  • Support for qualified and unqualified element/attribute forms
XSD Element Reference Resolution

The code generator now properly resolves XSD element references:

  • Global element references are fully resolved
  • Cross-schema element references are supported
  • Properties from referenced elements are properly inherited
  • Complex type references within elements are handled correctly
Improved Local Schema Resolution

When working with local WSDL files that reference external schemas:

  • Relative schema paths are correctly resolved
  • Local schema imports work seamlessly
  • Recursive schema resolution is supported with cycle detection
  • Mixed local and remote schema references are handled
Implementation Status

This implementation addresses all the features requested in issue #10, including the original TODOs:

  • ✅ Support for generating namespaces (main.go:41) - Complete namespace management system
  • ✅ Resolve XSD element references (main.go:39) - Full element reference resolution
  • ✅ Local schema resolution (main.go:37) - Enhanced local and remote schema handling
  • ✅ WSDL 2.0 Support - Complete parsing and code generation
  • ✅ Better error messages - Contextual errors with suggestions

All features include comprehensive test coverage and maintain backward compatibility with existing WSDL 1.1 code.

Project Structure

The project has been modularized for better maintainability and follows Go standard project layout:

gowsdl/
├── cmd/gowsdl/        # Command-line interface
│   └── main.go        # CLI entry point with extensive flag support
├── pkg/               # Core library packages
│   ├── core/          # Core utilities and error handling
│   ├── generator/     # Code generation logic
│   │   └── templates/ # Go templates for code generation
│   ├── http/          # HTTP client with security features
│   ├── parser/        # WSDL/XSD parsers (1.1 and 2.0)
│   ├── soap/          # SOAP protocol implementation
│   │   ├── auth/      # Authentication mechanisms
│   │   ├── client/    # SOAP client implementation
│   │   ├── encoding/  # SOAP encoding utilities
│   │   └── types/     # SOAP type definitions
│   ├── types/         # Type mapping and conversion
│   └── utils/         # General utility functions
├── fixtures/          # Test WSDL/XSD files
├── example/           # Usage examples
└── docs/              # Documentation
Recent Improvements
Security Enhancements
  • Path traversal prevention in file operations
  • Input validation for package names and file paths
  • Configurable TLS settings with custom CA certificates
  • Client certificate support for mutual TLS
  • Secure defaults for HTTPS connections
Modern Go Features
  • Context support for cancellation and timeouts
  • Wrapped errors with contextual information
  • Custom error types for better error handling
  • Go 1.21+ compatibility with latest Go idioms
HTTP Client Configuration
  • Configurable timeouts and retries
  • Rate limiting support
  • HTTP/HTTPS proxy support
  • Custom transport configuration
  • Connection pooling
Testing and Quality
  • 80%+ code coverage target
  • Unit tests throughout the codebase
  • Integration tests for end-to-end scenarios
  • Benchmark tests for performance monitoring
  • GitHub Actions CI/CD pipeline
Building and Testing
# Run all tests
go test -v -race ./...

# Run tests with coverage report
go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
go tool cover -html=coverage.out -o coverage.html

# Run integration tests
go test -tags=integration -v ./...

# Run benchmarks
go test -bench=. -benchmem ./...

# Run linter (install: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest)
golangci-lint run

# Update dependencies
go get -u ./...
go mod tidy
Contributing
  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Please ensure:

  • All tests pass (go test -v -race ./...)
  • Code coverage remains above 80% (go test -coverprofile=coverage.out ./...)
  • Linter passes (golangci-lint run)
  • New features include appropriate tests
License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	NewNamespaceManager     = core.NewNamespaceManager
	ParseLocation           = http.ParseLocation
	DefaultHTTPClientConfig = func() *HTTPClientConfig {
		return &HTTPClientConfig{
			Timeout:         30 * time.Second,
			MaxRetries:      0,
			RetryDelay:      1 * time.Second,
			MaxResponseSize: 10 * 1024 * 1024,
			UserAgent:       "gowsdl/1.0",
			TLSConfig: &tls.Config{
				MinVersion: tls.VersionTLS12,
			},
		}
	}
)

Re-export functions for backward compatibility

View Source 
var (
	MakePublic = utils.MakePublic
)

Utility functions exported for backward compatibility

Functions

This section is empty.

Types

type GoWSDL 

type GoWSDL struct {
	// contains filtered or unexported fields
}

GoWSDL is the main facade for WSDL code generation

func NewGoWSDL 

func NewGoWSDL(file string, opts ...Option) (*GoWSDL, error)

NewGoWSDL creates a new GoWSDL instance with the provided options

func NewGoWSDLWithConfig 

func NewGoWSDLWithConfig(file, pkg string, httpConfig *HTTPClientConfig, exportAllTypes bool) (*GoWSDL, error)

Legacy constructors for backward compatibility

func NewGoWSDLWithOptions 

func NewGoWSDLWithOptions(file, pkg string, httpConfig *HTTPClientConfig, exportAllTypes bool, useGenerics bool) (*GoWSDL, error)

func (*GoWSDL) Start 

func (g *GoWSDL) Start() (map[string][]byte, error)

Start initiates the code generation process

func (*GoWSDL) StartWithContext 

func (g *GoWSDL) StartWithContext(ctx context.Context) (map[string][]byte, error)

StartWithContext initiates the code generation process with context support

type HTTPClientConfig 

type HTTPClientConfig = http.HTTPClientConfig

Re-export functions for backward compatibility HTTPClientConfig is an alias for backward compatibility

type Location 

type Location = http.Location

Re-export types for backward compatibility

type NamespaceManager 

type NamespaceManager = core.NamespaceManager

Core types

type Option 

type Option func(*GoWSDL) error

Option defines a function that configures GoWSDL

func WithExportAllTypes 

func WithExportAllTypes(export bool) Option

WithExportAllTypes enables exporting all types (making them public)

func WithGenerics 

func WithGenerics() Option

WithGenerics enables Go generics code generation

func WithHTTPConfig 

func WithHTTPConfig(config *HTTPClientConfig) Option

WithHTTPConfig sets the HTTP client configuration

func WithPackage 

func WithPackage(pkg string) Option

WithPackage sets the package name for generated code

func WithServerGeneration 

func WithServerGeneration(generate bool) Option

WithServerGeneration enables server code generation

type SchemaError 

type SchemaError = types.SchemaError

Re-export types for backward compatibility

type WSDL 

type WSDL = parser.WSDL

Parser types

type WSDL2 

type WSDL2 = parser.WSDL2

Re-export types for backward compatibility

type WSDLBinding 

type WSDLBinding = parser.WSDLBinding

Re-export types for backward compatibility

type WSDLError 

type WSDLError = types.WSDLError

Error types

type WSDLImport 

type WSDLImport = parser.WSDLImport

Re-export types for backward compatibility

type WSDLOperation 

type WSDLOperation = parser.WSDLOperation

Re-export types for backward compatibility

type WSDLPort 

type WSDLPort = parser.WSDLPort

Re-export types for backward compatibility

type WSDLService 

type WSDLService = parser.WSDLService

Re-export types for backward compatibility

type XSDAttribute 

type XSDAttribute = parser.XSDAttribute

Re-export types for backward compatibility

type XSDComplexType 

type XSDComplexType = parser.XSDComplexType

Re-export types for backward compatibility

type XSDElement 

type XSDElement = parser.XSDElement

Re-export types for backward compatibility

type XSDImport 

type XSDImport = parser.XSDImport

Re-export types for backward compatibility

type XSDSchema 

type XSDSchema = parser.XSDSchema

Re-export types for backward compatibility

Source Files

View all Source files

Directories

Path Synopsis
cmd
gowsdl
Example showing how to use gowsdl with unqualified schema elements
 Example showing how to use gowsdl with unqualified schema elements
gen
inline_complex_demo
server
server/gen
pkg
core
generator
generator/templates
http
parser
types
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.