# Library for creating Woodpecker CI plugins

Provides basic structure and helpers to load Woodpecker CI environment variables while also
supporting reading Drone CI environment variables where available.

Adds logging support based on [zerolog](https://github.com/rs/zerolog) library and allows configurable
HTTP client library.

## Builtin settings

| Settings Name | Environment variable | Default | Description                                                                  |
| ------------- | -------------------- | ------- | ---------------------------------------------------------------------------- |
| `log_level`   | -                    | `info`  | Sets log level (`panic`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`) |
| `skip_verify` | -                    | `false` | Skip verification of TLS certificate                                         |
|               | `SOCKS_PROXY`        | _none_  | SOCKS5 proxy to use for connections                                          |
|               | `SOCKS_PROXY_OFF`    | _none_  | Do not use SOCKS5 proxy                                                      |

### Optional: HTTP proxy support

HTTP proxy support is **opt-in** and must be explicitly enabled by the plugin author via `EnableHTTPProxy: true` in `plugin.Options`. When enabled, the following settings become available:

| Settings Name | Environment variable | Default | Description                                            |
| ------------- | -------------------- | ------- | ------------------------------------------------------ |
| `http_proxy`  | `HTTP_PROXY`         | _none_  | HTTP proxy URL for outgoing connections                |
| `https_proxy` | `HTTPS_PROXY`        | _none_  | HTTPS proxy URL for outgoing connections               |
| `no_proxy`    | `NO_PROXY`           | _none_  | Comma-separated list of hosts to exclude from proxying |

The settings are resolved in the following order of precedence:

1. **Plugin settings** — `PLUGIN_HTTP_PROXY`, `PLUGIN_HTTPS_PROXY`, `PLUGIN_NO_PROXY`
2. **Lowercase env vars** — `http_proxy`, `https_proxy`, `no_proxy`
3. **Uppercase env vars** — `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`

Example Woodpecker CI pipeline configuration:

```yaml
steps:
  - name: my-plugin
    image: my-plugin:latest
    settings:
      http_proxy: http://proxy.example.com:3128
      https_proxy: http://proxy.example.com:3128
      no_proxy: "localhost,internal.example.com"
```

## Creating plugin

```go
package main

import (
	"context"

	"codeberg.org/woodpecker-plugins/go-plugin"
	"github.com/rs/zerolog/log"
	"github.com/urfave/cli/v3"
)

type Settings struct {
	// TODO: Plugin settings
	SampleFlag string
}

type Plugin struct {
	*plugin.Plugin
	Settings *Settings
}

func (p *Plugin) Flags() []cli.Flag {
	return []cli.Flag{
		// TODO: Add flags
		&cli.StringFlag{
			Name:        "sample.flag",
			Usage:       "sample flag",
			Sources:     cli.EnvVars("PLUGIN_SAMPLE_FLAG"),
			Destination: &p.Settings.SampleFlag,
		},
	}
}

func (p *Plugin) Execute(ctx context.Context) error {
	// TODO: Implement execution
	log.Debug().Msg("executed")
	return nil
}

func main() {
	p := &Plugin{
		Settings: &Settings{},
	}

	p.Plugin = plugin.New(plugin.Options{
		Name:            "sample-plugin",
		Description:     "Sample plugin",
		Flags:           p.Flags(),
		Execute:         p.Execute,
		EnableHTTPProxy: true, // opt-in to HTTP proxy support
	})

	p.Run()
}
```