pylego 0.1.31.1__py3-none-any.whl → 0.1.33__py3-none-any.whl

pylego/lego.go

@@ -11,8 +11,12 @@ import (
 	"encoding/pem"
 	"errors"
 	"fmt"
+	"net"
 	"os"
+	"strings"
+	"time"
 
+	"github.com/go-acme/lego/v4/acme"
 	"github.com/go-acme/lego/v4/certcrypto"
 	"github.com/go-acme/lego/v4/certificate"
 	"github.com/go-acme/lego/v4/challenge/dns01"
@@ -23,13 +27,30 @@ import (
 	"github.com/go-acme/lego/v4/registration"
 )
 
+// Error code constants
+const (
+	ErrInvalidArguments          = "invalid_arguments"
+	ErrInvalidEnvironment        = "invalid_environment"
+	ErrCertificateRequestFailed  = "certificate_request_failed"
+	ErrInvalidPrivateKey         = "invalid_private_key"
+	ErrKeyGenerationFailed       = "key_generation_failed"
+	ErrLegoClientCreationFailed  = "lego_client_creation_failed"
+	ErrDNSProviderFailed         = "dns_provider_failed"
+	ErrAccountRegistrationFailed = "account_registration_failed"
+	ErrInvalidCSR                = "invalid_csr"
+	ErrCertificateObtainFailed   = "certificate_obtain_failed"
+	ErrNetworkError              = "network_error"
+	ErrMarshalingFailed          = "marshaling_failed"
+)
+
 type LegoInputArgs struct {
-	Email      string `json:"email"`
-	PrivateKey string `json:"private_key,omitempty"`
-	Server     string `json:"server"`
-	CSR        string `json:"csr"`
-	Plugin     string `json:"plugin"`
-	Env        map[string]string
+	Email              string `json:"email"`
+	PrivateKey         string `json:"private_key,omitempty"`
+	Server             string `json:"server"`
+	CSR                string `json:"csr"`
+	Plugin             string `json:"plugin"`
+	Env                map[string]string
+	DNSPropagationWait int `json:"dns_propagation_wait,omitempty"`
 }
 
 type LegoOutputResponse struct {
@@ -46,42 +67,217 @@ type Metadata struct {
 	Domain    string `json:"domain"`
 }
 
+type Subproblem struct {
+	Type       string     `json:"type"`                 // Error type URN
+	Detail     string     `json:"detail"`               // Human-readable message
+	Identifier Identifier `json:"identifier,omitempty"` // The identifier that caused this subproblem
+}
+
+type Identifier struct {
+	Type  string `json:"type"`  // "dns" or "ip"
+	Value string `json:"value"` // Domain name or IP address
+}
+
+type ErrorResponse struct {
+	Type        string       `json:"type"`                  // "acme" for CA server errors, "lego" for everything else
+	Code        string       `json:"code"`                  // Error code or category
+	Status      *int         `json:"status,omitempty"`      // HTTP status if applicable (ACME errors)
+	Detail      string       `json:"detail"`                // Human-readable message
+	ACMEType    string       `json:"acme_type,omitempty"`   // Full ACME URN if applicable
+	Subproblems []Subproblem `json:"subproblems,omitempty"` // Detailed subproblems from ACME errors
+}
+
+type LegoResponse struct {
+	Success bool                `json:"success"`
+	Error   *ErrorResponse      `json:"error,omitempty"`
+	Data    *LegoOutputResponse `json:"data,omitempty"`
+}
+
+func isNetworkError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var (
+		netErr net.Error
+		dnsErr *net.DNSError
+		opErr  *net.OpError
+	)
+
+	switch {
+	case errors.As(err, &netErr):
+		return true
+	case errors.As(err, &dnsErr):
+		return true
+	case errors.As(err, &opErr):
+		return true
+	default:
+		return false
+	}
+}
+
+func extractSubproblems(problemDetails *acme.ProblemDetails) []Subproblem {
+	var subproblems []Subproblem
+	for _, sub := range problemDetails.SubProblems {
+		subCode := "unknown"
+		if sub.Type != "" {
+			parts := strings.Split(sub.Type, ":")
+			if len(parts) > 0 {
+				subCode = parts[len(parts)-1]
+			}
+		}
+		subproblems = append(subproblems, Subproblem{
+			Type:   subCode,
+			Detail: sub.Detail,
+			Identifier: Identifier{
+				Type:  sub.Identifier.Type,
+				Value: sub.Identifier.Value,
+			},
+		})
+	}
+	return subproblems
+}
+
+func wrapError(err error, context string) *ErrorResponse {
+	if err == nil {
+		return nil
+	}
+
+	var ctxErr *contextError
+	if errors.As(err, &ctxErr) {
+		context = ctxErr.context
+		err = ctxErr.original
+	}
+
+	var problemDetails *acme.ProblemDetails
+	if errors.As(err, &problemDetails) {
+		code := "unknown"
+		if problemDetails.Type != "" {
+			parts := strings.Split(problemDetails.Type, ":")
+			if len(parts) > 0 {
+				code = parts[len(parts)-1]
+			}
+		}
+		status := problemDetails.HTTPStatus
+
+		return &ErrorResponse{
+			Type:        "acme",
+			Code:        code,
+			Status:      &status,
+			Detail:      problemDetails.Detail,
+			ACMEType:    problemDetails.Type,
+			Subproblems: extractSubproblems(problemDetails),
+		}
+	}
+
+	if isNetworkError(err) {
+		return &ErrorResponse{
+			Type:   "lego",
+			Code:   ErrNetworkError,
+			Detail: err.Error(),
+		}
+	}
+
+	return &ErrorResponse{
+		Type:   "lego",
+		Code:   context,
+		Detail: err.Error(),
+	}
+}
+
+func buildErrorResponse(err error, context string) *C.char {
+	response := LegoResponse{
+		Success: false,
+		Error:   wrapError(err, context),
+	}
+	responseJSON, marshalErr := json.Marshal(response)
+	if marshalErr == nil {
+		return C.CString(string(responseJSON))
+	}
+
+	fallbackResponse := LegoResponse{
+		Success: false,
+		Error: &ErrorResponse{
+			Type:   "lego",
+			Code:   ErrMarshalingFailed,
+			Detail: marshalErr.Error(),
+		},
+	}
+	fallbackJSON, _ := json.Marshal(fallbackResponse)
+
+	return C.CString(string(fallbackJSON))
+}
+
+func buildSuccessResponse(data *LegoOutputResponse) *C.char {
+	response := LegoResponse{
+		Success: true,
+		Data:    data,
+	}
+	responseJSON, marshalErr := json.Marshal(response)
+	if marshalErr == nil {
+		return C.CString(string(responseJSON))
+	}
+
+	fallbackResponse := LegoResponse{
+		Success: false,
+		Error: &ErrorResponse{
+			Type:   "lego",
+			Code:   ErrMarshalingFailed,
+			Detail: marshalErr.Error(),
+		},
+	}
+	fallbackJSON, _ := json.Marshal(fallbackResponse)
+
+	return C.CString(string(fallbackJSON))
+}
+
+type contextError struct {
+	original error
+	context  string
+}
+
+func (e *contextError) Error() string {
+	return e.original.Error()
+}
+
+func (e *contextError) Unwrap() error {
+	return e.original
+}
+
+func wrapWithContext(err error, context string) error {
+	return &contextError{original: err, context: context}
+}
+
 //export RunLegoCommand
 func RunLegoCommand(message *C.char) *C.char {
 	CLIArgs, err := extractArguments(C.GoString(message))
 	if err != nil {
-		return C.CString(fmt.Sprint("error: couldn't extract arguments: ", err))
+		return buildErrorResponse(err, ErrInvalidArguments)
 	}
 	for k, v := range CLIArgs.Env {
 		if err := os.Setenv(k, v); err != nil {
-			return C.CString(fmt.Sprint("error: couldn't load environment variables: ", err))
+			return buildErrorResponse(err, ErrInvalidEnvironment)
 		}
 
 	}
-	certificate, err := requestCertificate(CLIArgs.Email, CLIArgs.PrivateKey, CLIArgs.Server, CLIArgs.CSR, CLIArgs.Plugin)
+	certificate, err := requestCertificate(CLIArgs.Email, CLIArgs.PrivateKey, CLIArgs.Server, CLIArgs.CSR, CLIArgs.Plugin, CLIArgs.DNSPropagationWait)
 	if err != nil {
-		return C.CString(fmt.Sprint("error: couldn't request certificate: ", err))
+		return buildErrorResponse(err, ErrCertificateRequestFailed)
 	}
-	response_json, err := json.Marshal(certificate)
-	if err != nil {
-		return C.CString(fmt.Sprint("error: coudn't build response message: ", err))
-	}
-	return_message_ptr := C.CString(string(response_json))
-	return return_message_ptr
+	return buildSuccessResponse(certificate)
 }
 
-func requestCertificate(email, privateKeyPem, server, csr, plugin string) (*LegoOutputResponse, error) {
+func requestCertificate(email, privateKeyPem, server, csr, plugin string, propagationWait int) (*LegoOutputResponse, error) {
 	var privateKey crypto.PrivateKey
 	if privateKeyPem != "" {
 		parsedKey, err := certcrypto.ParsePEMPrivateKey([]byte(privateKeyPem))
 		if err != nil {
-			return nil, fmt.Errorf("couldn't parse private key: %s", err)
+			return nil, wrapWithContext(err, ErrInvalidPrivateKey)
 		}
 		privateKey = parsedKey
 	} else {
 		generatedKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
 		if err != nil {
-			return nil, fmt.Errorf("couldn't generate priv key: %s", err)
+			return nil, wrapWithContext(err, ErrKeyGenerationFailed)
 		}
 		privateKey = generatedKey
 	}
@@ -96,27 +292,27 @@ func requestCertificate(email, privateKeyPem, server, csr, plugin string) (*Lego
 
 	client, err := lego.NewClient(config)
 	if err != nil {
-		return nil, fmt.Errorf("couldn't create lego client: %s", err)
+		return nil, wrapWithContext(err, ErrLegoClientCreationFailed)
 	}
 
-	err = configureClientChallenges(client, plugin)
+	err = configureClientChallenges(client, plugin, propagationWait)
 	if err != nil {
-		return nil, fmt.Errorf("couldn't configure client challenges: %s", err)
+		return nil, wrapWithContext(err, ErrDNSProviderFailed)
 	}
 
 	reg, err := client.Registration.Register(registration.RegisterOptions{TermsOfServiceAgreed: true})
 	if err != nil {
-		return nil, fmt.Errorf("couldn't register user: %s", err)
+		return nil, wrapWithContext(err, ErrAccountRegistrationFailed)
 	}
 	user.Registration = reg
 
 	block, _ := pem.Decode([]byte(csr))
 	if block == nil || block.Type != "CERTIFICATE REQUEST" {
-		return nil, errors.New("failed to decode PEM block containing certificate request")
+		return nil, wrapWithContext(errors.New("failed to decode PEM block"), ErrInvalidCSR)
 	}
 	csrObject, err := x509.ParseCertificateRequest(block.Bytes)
 	if err != nil {
-		return nil, fmt.Errorf("failed to parse certificate request: %s", err)
+		return nil, wrapWithContext(err, ErrInvalidCSR)
 	}
 	request := certificate.ObtainForCSRRequest{
 		CSR:    csrObject,
@@ -124,7 +320,7 @@ func requestCertificate(email, privateKeyPem, server, csr, plugin string) (*Lego
 	}
 	certificates, err := client.Certificate.ObtainForCSR(request)
 	if err != nil {
-		return nil, fmt.Errorf("coudn't obtain cert: %s", err)
+		return nil, wrapWithContext(err, ErrCertificateObtainFailed)
 	}
 
 	return &LegoOutputResponse{
@@ -140,7 +336,7 @@ func requestCertificate(email, privateKeyPem, server, csr, plugin string) (*Lego
 	}, nil
 }
 
-func configureClientChallenges(client *lego.Client, plugin string) error {
+func configureClientChallenges(client *lego.Client, plugin string, propagationWait int) error {
 	switch plugin {
 	case "", "http":
 		if err := client.Challenge.SetHTTP01Provider(http01.NewProviderServer(os.Getenv("HTTP01_IFACE"), os.Getenv("HTTP01_PORT"))); err != nil {
@@ -157,9 +353,16 @@ func configureClientChallenges(client *lego.Client, plugin string) error {
 		if err != nil {
 			return errors.Join(fmt.Errorf("couldn't create %s provider: ", plugin), err)
 		}
+		var wait time.Duration
+		if propagationWait > 0 {
+			wait = time.Duration(propagationWait) * time.Second
+		}
+
 		err = client.Challenge.SetDNS01Provider(dnsProvider,
 			dns01.CondOption(os.Getenv("DNS_PROPAGATION_DISABLE_ANS") != "",
 				dns01.DisableAuthoritativeNssPropagationRequirement()),
+			dns01.CondOption(wait > 0,
+				dns01.PropagationWait(wait, true)),
 			dns01.CondOption(os.Getenv("DNS_PROPAGATION_RNS") != "", dns01.RecursiveNSsPropagationRequirement()))
 		if err != nil {
 			return errors.Join(fmt.Errorf("couldn't set %s DNS provider server: ", plugin), err)

pylego/pylego.py

@@ -10,6 +10,23 @@ so_file = here / ("lego.so")
 library = ctypes.cdll.LoadLibrary(so_file)
 
 
+@dataclass
+class Identifier:
+    """ACME identifier (domain or IP)."""
+
+    type: str  # "dns" or "ip"
+    value: str  # Domain name or IP address
+
+
+@dataclass
+class Subproblem:
+    """ACME subproblem details."""
+
+    type: str  # Error type (e.g., "unauthorized", "dns")
+    detail: str  # Human-readable message
+    identifier: Identifier  # The identifier that caused this subproblem
+
+
 @dataclass
 class Metadata:
     """Extra information returned by the ACME server."""
@@ -31,11 +48,49 @@ class LEGOResponse:
 
 
 class LEGOError(Exception):
-    """Exceptions that are returned from the LEGO Go library."""
+    """Unified exception for all errors returned by the lego invocation.
+
+    Attributes:
+        type: source of the error. "acme" when coming from the ACME server, otherwise "lego".
+        code: error code/category. For ACME, this is derived from the ACME problem type; otherwise, it's set by lego.
+        status: HTTP status code for ACME errors, None otherwise.
+        detail: human-readable description of the error.
+        acme_type: full ACME problem type (URN), present only for ACME errors.
+        subproblems: list of Subproblem objects with detailed error information.
+        info: dictionary with the raw error information returned by the underlying call.
+    """
+
+    def __init__(
+        self,
+        detail: str,
+        *,
+        type: str = "lego",
+        code: str = "",
+        status: int | None = None,
+        acme_type: str = "",
+        subproblems: list[Subproblem] | None = None,
+        info: dict | None = None,
+    ):
+        # Include code in exception message for better error display
+        message = f"[{code}] {detail}" if code else detail
+        super().__init__(message)
+        self.type = type
+        self.code = code
+        self.status = status
+        self.detail = detail
+        self.acme_type = acme_type
+        self.subproblems = subproblems or []
+        self.info = info or {}
 
 
 def run_lego_command(
-    email: str, server: str, csr: bytes, env: dict[str, str], plugin: str = "", private_key: str = ""
+    email: str,
+    server: str,
+    csr: bytes,
+    env: dict[str, str],
+    plugin: str = "",
+    private_key: str = "",
+    dns_propagation_wait: int | None = None,
 ) -> LEGOResponse:
     """Run an arbitrary command in the Lego application. Read more at https://go-acme.github.io.
 
@@ -47,25 +102,66 @@ def run_lego_command(
         env: the environment variables required for the chosen plugin.
         private_key: the private key to be used for the registration on the ACME server (not the private key used to sign the CSR).
             If not provided, a new one will be generated.
+        dns_propagation_wait: optional wait duration for DNS propagation, in seconds (int).
     """
     library.RunLegoCommand.restype = ctypes.c_char_p
     library.RunLegoCommand.argtypes = [ctypes.c_char_p]
 
+    if dns_propagation_wait is not None and dns_propagation_wait < 0:
+        raise ValueError("dns_propagation_wait cannot be negative")
+
+    payload = {
+        "email": email,
+        "server": server,
+        "csr": csr.decode(),
+        "plugin": plugin,
+        "env": env,
+        "private_key": private_key,
+    }
+    if dns_propagation_wait is not None:
+        payload["dns_propagation_wait"] = dns_propagation_wait
+
     message = bytes(
-        json.dumps(
-            {
-                "email": email,
-                "server": server,
-                "csr": csr.decode(),
-                "plugin": plugin,
-                "env": env,
-                "private_key": private_key,
-            }
-        ),
+        json.dumps(payload),
         "utf-8",
     )
     result: bytes = library.RunLegoCommand(message)
-    if result.startswith(b"error:"):
-        raise LEGOError(result.decode())
-    result_dict = json.loads(result.decode("utf-8"))
-    return LEGOResponse(**{**result_dict, "metadata": Metadata(**result_dict.get("metadata"))})
+    result_str = result.decode("utf-8")
+
+    try:
+        result_dict = json.loads(result_str)
+    except json.JSONDecodeError as e:
+        raise LEGOError(f"Failed to parse response: {result_str}") from e
+
+    if not result_dict.get("success", False):
+        error_info: dict = result_dict.get("error", {})
+        err_source = error_info.get("type", "lego")
+        detail = error_info.get("detail", "Unknown error occurred")
+
+        subproblems = []
+        for sub_dict in error_info.get("subproblems", []):
+            identifier_dict = sub_dict.get("identifier", {})
+            subproblems.append(
+                Subproblem(
+                    type=sub_dict.get("type", ""),
+                    detail=sub_dict.get("detail", ""),
+                    identifier=Identifier(
+                        type=identifier_dict.get("type", ""),
+                        value=identifier_dict.get("value", ""),
+                    ),
+                )
+            )
+
+        info = dict(error_info)
+        raise LEGOError(
+            detail,
+            type="acme" if err_source == "acme" else "lego",
+            code=error_info.get("code", ""),
+            status=error_info.get("status"),
+            acme_type=error_info.get("acme_type", "") if err_source == "acme" else "",
+            subproblems=subproblems,
+            info=info,
+        )
+
+    data = result_dict.get("data", {})
+    return LEGOResponse(**{**data, "metadata": Metadata(**data.get("metadata", {}))})

{pylego-0.1.31.1.dist-info → pylego-0.1.33.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylego
-Version: 0.1.31.1
+Version: 0.1.33
 Summary: A python wrapper package for the lego application written in Golang
 Author-email: Canonical <telco-engineers@lists.canonical.com>
 Project-URL: Homepage, https://github.com/canonical/pylego
@@ -63,6 +63,29 @@ On top of the environment variables that LEGO supports, we have some extra ones
 | `TLSALPN01_IFACE` | Interface for the TLS-ALPN-01 challenge (when `plugin=tls`). Any interface by default.                                        |
 | `TLSALPN01_PORT`  | Port for the TLS-ALPN-01 challenge (when `plugin=tls`). 443 by default.                                                       |
 
+## Error Handling
+
+All errors raised by `run_lego_command()` are `LEGOError` exceptions with structured information:
+
+```python
+from pylego import run_lego_command, LEGOError
+
+try:
+    result = run_lego_command(...)
+except LEGOError as e:
+    print(f"Error: {e}")              # Includes error code in message
+    print(f"Type: {e.type}")          # "acme" (server) or "lego" (client)
+    print(f"Code: {e.code}")          # e.g., "invalid_csr", "dns_provider_failed"
+    print(f"Detail: {e.detail}")      # Human-readable message
+
+    # ACME-specific fields
+    if e.type == "acme":
+        print(f"Status: {e.status}")      # HTTP status code
+        print(f"Subproblems: {e.subproblems}")  # Validation details per domain
+```
+
+Common error codes: `invalid_csr`, `invalid_private_key`, `dns_provider_failed`, `network_error`, `certificate_obtain_failed`. ACME errors include codes like `unauthorized`, `rateLimited`, `dns`.
+
 ## How does it work?
 
 Golang supports building a shared c library from its CLI build tool. We import and use the LEGO application from GoLang, and provide a stub with C bindings so that the shared C binary we produce exposes a C API for other programs to import and utilize. pylego then uses the [ctypes](https://docs.python.org/3/library/ctypes.html) standard library in python to load this binary, and make calls to its methods.

pylego-0.1.33.dist-info/RECORD

@@ -0,0 +1,11 @@
+pylego/__init__.py,sha256=7rcUcQcOWsOLxTOEXF2ASkwm_7eED1UIXzxdlgKPr5c,82
+pylego/go.mod,sha256=jNERhSIs38s6uxlVwLn8RRpyvax-jgmQWyBfTLY77VI,11182
+pylego/go.sum,sha256=dHaqyMv51JXWRjlWu_fx_pftQul6kgUo8hJButcuJUI,143991
+pylego/lego.go,sha256=zauvVfyFVfH_4Z1lAiTAYRt-tU-0Z4_xmVjKhkP7uu8,11180
+pylego/lego.so,sha256=wAWQFSFsD2vd1nGr3FTdGwUUfliICwvxGhMnvSf7m9c,87373536
+pylego/pylego.py,sha256=556axo5EwOUGG5ZtsHgfFog-CTkJtOsavdTGLgEAu6k,5522
+pylego-0.1.33.dist-info/licenses/LICENSE,sha256=aklz9Y8CIpFsN61U4jHlJYp4W_8HoDpY-tINlDcdSZY,10934
+pylego-0.1.33.dist-info/METADATA,sha256=NpHliVBR4KXDmSkiL354ciOurbesYKk6hixgGKM7CZQ,6703
+pylego-0.1.33.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+pylego-0.1.33.dist-info/top_level.txt,sha256=pSOYv55_w90qy3xOvqz_ysSz-X-XRTb-jMpiOyLNnNs,7
+pylego-0.1.33.dist-info/RECORD,,

{pylego-0.1.31.1.dist-info → pylego-0.1.33.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pylego-0.1.31.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-pylego/__init__.py,sha256=7rcUcQcOWsOLxTOEXF2ASkwm_7eED1UIXzxdlgKPr5c,82
-pylego/go.mod,sha256=2zddNtfcY9OT_qrCABQwRB06dvL0QF9kMA1E6lmvOlM,12467
-pylego/go.sum,sha256=-Gl6lIAbKb0cjJHr4dVvA4_XGBSHONqL0lKRGHUoYn0,187420
-pylego/lego.go,sha256=O_tXZN6DRXlVXJfZdjIXTrDWXyn1UuBeZa_ZzPCnGOA,6004
-pylego/lego.so,sha256=nlASF8T39I3b6NodVaPofEqOs1c5Fu6b0zxvn8KI6MM,87291672
-pylego/pylego.py,sha256=x9NTkBi1P4ITPhGBUgMCHVBHqFN7NXAJAc9aknKLcgk,2263
-pylego-0.1.31.1.dist-info/licenses/LICENSE,sha256=aklz9Y8CIpFsN61U4jHlJYp4W_8HoDpY-tINlDcdSZY,10934
-pylego-0.1.31.1.dist-info/METADATA,sha256=rh0voQ1R8_NHfbYvivFzVlMoF5sNOEi6Ua0ikdA6Ea8,5778
-pylego-0.1.31.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pylego-0.1.31.1.dist-info/top_level.txt,sha256=pSOYv55_w90qy3xOvqz_ysSz-X-XRTb-jMpiOyLNnNs,7
-pylego-0.1.31.1.dist-info/RECORD,,