v3.0.0 (#18)

2026-08-12 10:22:14 +01:00 · 2018-12-10 16:09:19 +01:00
parent c1f6100382
commit 495203c112
473 changed files with 4631 additions and 174161 deletions
--- a/pkg/README.md
+++ b/pkg/README.md
@@ -0,0 +1,37 @@
+# Gotenberg Go client
+
+A simple Go client for interacting with a Gotenberg API.
+
+## Install
+
+```bash
+$ go get -u github.com/thecodingmachine/gotenberg
+```
+
+## Usage
+
+```golang
+import "github.com/thecodingmachine/gotenberg/pkg"
+
+func main() {
+    // HTML conversion example.
+    c := &gotenberg.Client{Hostname: "http://localhost:3000"}
+    req := &gotenberg.HTMLRequest{
+        IndexFilePath: "index.html",
+        AssetFilePaths: []string{
+            "style.css",
+            "img.png",
+        },
+        Options: &gotenberg.HTMLOptions{
+            HeaderFilePath: "header.html",
+            FooterFilePath: "footer.html",
+            PaperSize:      gotenberg.A4,
+            PaperMargins:   gotenberg.NormalMargins,  
+        },
+    }
+    dest := "foo.pdf"
+    c.Store(req, dest)
+}
+```
+
+For more complete usages, head to the [documentation](https://thecodingmachine.gotenberg.github.io).
--- a/pkg/client.go
+++ b/pkg/client.go
@@ -0,0 +1,155 @@
+package gotenberg
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+)
+
+const (
+	webhookURL   string = "webhookURL"
+	paperWidth   string = "paperWidth"
+	paperHeight  string = "paperHeight"
+	marginTop    string = "marginTop"
+	marginBottom string = "marginBottom"
+	marginLeft   string = "marginLeft"
+	marginRight  string = "marginRight"
+	landscape    string = "landscape"
+)
+
+var (
+	// A3 paper size.
+	A3 = [2]float64{11.7, 16.5}
+	// A4 paper size.
+	A4 = [2]float64{8.27, 11.7}
+	// A5 paper size.
+	A5 = [2]float64{5.8, 8.3}
+	// A6 paper size.
+	A6 = [2]float64{4.1, 5.8}
+	// Letter paper size.
+	Letter = [2]float64{8.5, 11}
+	// Legal paper size.
+	Legal = [2]float64{8.5, 14}
+	// Tabloid paper size.
+	Tabloid = [2]float64{11, 17}
+)
+
+var (
+	// NoMargins removes margins.
+	NoMargins = [4]float64{0, 0, 0, 0}
+	// NormalMargins uses 1 inche margins.
+	NormalMargins = [4]float64{1, 1, 1, 1}
+	// LargeMargins uses 2 inche margins.
+	LargeMargins = [4]float64{2, 2, 2, 2}
+)
+
+// Client facilitates interacting with
+// the Gotenberg API.
+type Client struct {
+	Hostname string
+}
+
+// Request is a type for sending
+// form values and form files to
+// the Gotenberg API.
+type Request interface {
+	validate() error
+	getPostURL() string
+	getFormValues() map[string]string
+	getFormFiles() map[string]string
+}
+
+// Post sends a request to the Gotenberg API
+// and returns the response.
+func (c *Client) Post(req Request) (*http.Response, error) {
+	if err := req.validate(); err != nil {
+		return nil, err
+	}
+	body, contentType, err := multipartForm(req)
+	if err != nil {
+		return nil, err
+	}
+	URL := fmt.Sprintf("%s%s", c.Hostname, req.getPostURL())
+	resp, err := http.Post(URL, contentType, body)
+	if err != nil {
+		return nil, err
+	}
+	return resp, nil
+}
+
+// Store creates the resulting PDF to given destination.
+func (c *Client) Store(req Request, dest string) error {
+	if hasWebhook(req) {
+		return errors.New("cannot use Store method with a webhook")
+	}
+	resp, err := c.Post(req)
+	if err != nil {
+		return err
+	}
+	return writeNewFile(dest, resp.Body)
+}
+
+func hasWebhook(req Request) bool {
+	webhookURL, ok := req.getFormValues()[webhookURL]
+	if !ok {
+		return false
+	}
+	return webhookURL != ""
+}
+
+func writeNewFile(fpath string, in io.Reader) error {
+	if err := os.MkdirAll(filepath.Dir(fpath), 0755); err != nil {
+		return fmt.Errorf("%s: making directory for file: %v", fpath, err)
+	}
+	out, err := os.Create(fpath)
+	if err != nil {
+		return fmt.Errorf("%s: creating new file: %v", fpath, err)
+	}
+	defer out.Close()
+	err = out.Chmod(0644)
+	if err != nil && runtime.GOOS != "windows" {
+		return fmt.Errorf("%s: changing file mode: %v", fpath, err)
+	}
+	_, err = io.Copy(out, in)
+	if err != nil {
+		return fmt.Errorf("%s: writing file: %v", fpath, err)
+	}
+	return nil
+}
+
+func fileExists(name string) bool {
+	_, err := os.Stat(name)
+	return !os.IsNotExist(err)
+}
+
+func multipartForm(req Request) (*bytes.Buffer, string, error) {
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+	defer writer.Close()
+	for filename, fpath := range req.getFormFiles() {
+		in, err := os.Open(fpath)
+		if err != nil {
+			return nil, "", fmt.Errorf("%s: opening file: %v", filename, err)
+		}
+		part, err := writer.CreateFormFile("files", filename)
+		if err != nil {
+			return nil, "", fmt.Errorf("%s: creating form file: %v", filename, err)
+		}
+		_, err = io.Copy(part, in)
+		if err != nil {
+			return nil, "", fmt.Errorf("%s: copying file: %v", filename, err)
+		}
+	}
+	for name, value := range req.getFormValues() {
+		if err := writer.WriteField(name, value); err != nil {
+			return nil, "", fmt.Errorf("%s: writting form field: %v", name, err)
+		}
+	}
+	return body, writer.FormDataContentType(), nil
+}
--- a/pkg/doc.go
+++ b/pkg/doc.go
@@ -0,0 +1,31 @@
+/*
+Package gotenberg is a Go client for
+interacting with a Gotenberg API.
+
+For instance, if you want to convert HTML:
+
+ import "github.com/thecodingmachine/gotenberg/pkg"
+
+ func main() {
+     // HTML conversion example.
+     c := &gotenberg.Client{Hostname: "http://localhost:3000"}
+     req := &gotenberg.HTMLRequest{
+         IndexFilePath: "index.html",
+         AssetFilePaths: []string{
+             "style.css",
+             "img.png",
+         },
+         Options: &gotenberg.HTMLOptions{
+             HeaderFilePath: "header.html",
+		     FooterFilePath: "footer.html",
+		     PaperSize:      gotenberg.A4,
+		     PaperMargins:   gotenberg.NormalMargins,
+         },
+     }
+     dest := "foo.pdf"
+     c.Store(req, dest)
+ }
+
+For more complete usages, head to the https://thecodingmachine.gotenberg.github.io.
+*/
+package gotenberg
--- a/pkg/html.go
+++ b/pkg/html.go
@@ -0,0 +1,78 @@
+package gotenberg
+
+import (
+	"fmt"
+	"path/filepath"
+	"strconv"
+)
+
+// HTMLRequest facilitates HTML conversion
+// with the Gotenberg API.
+type HTMLRequest struct {
+	IndexFilePath  string
+	AssetFilePaths []string
+	Options        *HTMLOptions
+}
+
+// HTMLOptions gathers all options
+// for HTML conversion with the Gotenberg API.
+type HTMLOptions struct {
+	WebHookURL     string
+	HeaderFilePath string
+	FooterFilePath string
+	PaperSize      [2]float64
+	PaperMargins   [4]float64
+	Landscape      bool
+}
+
+func (html *HTMLRequest) validate() error {
+	if !fileExists(html.IndexFilePath) {
+		return fmt.Errorf("%s: index file does not exist", html.IndexFilePath)
+	}
+	if html.Options.HeaderFilePath != "" && !fileExists(html.Options.HeaderFilePath) {
+		return fmt.Errorf("%s: header file does not exist", html.Options.HeaderFilePath)
+	}
+	if html.Options.FooterFilePath != "" && !fileExists(html.Options.FooterFilePath) {
+		return fmt.Errorf("%s: footer file does not exist", html.Options.FooterFilePath)
+	}
+	return nil
+}
+
+func (html *HTMLRequest) getPostURL() string {
+	return "/convert/html"
+}
+
+func (html *HTMLRequest) getFormValues() map[string]string {
+	if html.Options == nil {
+		html.Options = &HTMLOptions{}
+	}
+	values := make(map[string]string)
+	values[webhookURL] = html.Options.WebHookURL
+	values[paperWidth] = fmt.Sprintf("%f", html.Options.PaperSize[0])
+	values[paperHeight] = fmt.Sprintf("%f", html.Options.PaperSize[1])
+	values[marginTop] = fmt.Sprintf("%f", html.Options.PaperMargins[0])
+	values[marginBottom] = fmt.Sprintf("%f", html.Options.PaperMargins[1])
+	values[marginLeft] = fmt.Sprintf("%f", html.Options.PaperMargins[2])
+	values[marginRight] = fmt.Sprintf("%f", html.Options.PaperMargins[3])
+	values[landscape] = strconv.FormatBool(html.Options.Landscape)
+	return values
+}
+
+func (html *HTMLRequest) getFormFiles() map[string]string {
+	if html.Options == nil {
+		html.Options = &HTMLOptions{}
+	}
+	files := make(map[string]string)
+	files["index.html"] = html.IndexFilePath
+	files["header.html"] = html.Options.HeaderFilePath
+	files["footer.html"] = html.Options.FooterFilePath
+	for _, fpath := range html.AssetFilePaths {
+		files[filepath.Base(fpath)] = fpath
+	}
+	return files
+}
+
+// Compile-time checks to ensure type implements desired interfaces.
+var (
+	_ = Request(new(HTMLRequest))
+)
--- a/pkg/html_test.go
+++ b/pkg/html_test.go
@@ -0,0 +1,38 @@
+package gotenberg
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/thecodingmachine/gotenberg/internal/pkg/rand"
+	"github.com/thecodingmachine/gotenberg/test"
+)
+
+func TestHTML(t *testing.T) {
+	c := &Client{Hostname: "http://localhost:3000"}
+	req := &HTMLRequest{
+		IndexFilePath: test.HTMLTestFilePath(t, "index.html"),
+		AssetFilePaths: []string{
+			test.HTMLTestFilePath(t, "font.woff"),
+			test.HTMLTestFilePath(t, "img.gif"),
+			test.HTMLTestFilePath(t, "style.css"),
+		},
+		Options: &HTMLOptions{
+			HeaderFilePath: test.HTMLTestFilePath(t, "header.html"),
+			FooterFilePath: test.HTMLTestFilePath(t, "footer.html"),
+			PaperSize:      A4,
+			PaperMargins:   NormalMargins,
+		},
+	}
+	dirPath, err := rand.Get()
+	require.Nil(t, err)
+	dest := fmt.Sprintf("%s/foo.pdf", dirPath)
+	err = c.Store(req, dest)
+	assert.Nil(t, err)
+	assert.FileExists(t, dest)
+	err = os.RemoveAll(dirPath)
+	assert.Nil(t, err)
+}
--- a/pkg/markdown.go
+++ b/pkg/markdown.go
@@ -0,0 +1,87 @@
+package gotenberg
+
+import (
+	"fmt"
+	"path/filepath"
+	"strconv"
+)
+
+// MarkdownRequest facilitates Markdown conversion
+// with the Gotenberg API.
+type MarkdownRequest struct {
+	IndexFilePath     string
+	MarkdownFilePaths []string
+	AssetFilePaths    []string
+	Options           *MarkdownOptions
+}
+
+// MarkdownOptions gathers all options
+// for Markdown conversion with the Gotenberg API.
+type MarkdownOptions struct {
+	WebHookURL     string
+	HeaderFilePath string
+	FooterFilePath string
+	PaperSize      [2]float64
+	PaperMargins   [4]float64
+	Landscape      bool
+}
+
+func (markdown *MarkdownRequest) validate() error {
+	if !fileExists(markdown.IndexFilePath) {
+		return fmt.Errorf("%s: index file does not exist", markdown.IndexFilePath)
+	}
+	if markdown.Options.HeaderFilePath != "" && !fileExists(markdown.Options.HeaderFilePath) {
+		return fmt.Errorf("%s: header file does not exist", markdown.Options.HeaderFilePath)
+	}
+	if markdown.Options.FooterFilePath != "" && !fileExists(markdown.Options.FooterFilePath) {
+		return fmt.Errorf("%s: footer file does not exist", markdown.Options.FooterFilePath)
+	}
+	for _, fpath := range markdown.MarkdownFilePaths {
+		if !fileExists(fpath) {
+			return fmt.Errorf("%s: markdown file does not exist", fpath)
+		}
+	}
+	return nil
+}
+
+func (markdown *MarkdownRequest) getPostURL() string {
+	return "/convert/markdown"
+}
+
+func (markdown *MarkdownRequest) getFormValues() map[string]string {
+	if markdown.Options == nil {
+		markdown.Options = &MarkdownOptions{}
+	}
+	values := make(map[string]string)
+	values[webhookURL] = markdown.Options.WebHookURL
+	values[paperWidth] = fmt.Sprintf("%f", markdown.Options.PaperSize[0])
+	values[paperHeight] = fmt.Sprintf("%f", markdown.Options.PaperSize[1])
+	values[marginTop] = fmt.Sprintf("%f", markdown.Options.PaperMargins[0])
+	values[marginBottom] = fmt.Sprintf("%f", markdown.Options.PaperMargins[1])
+	values[marginLeft] = fmt.Sprintf("%f", markdown.Options.PaperMargins[2])
+	values[marginRight] = fmt.Sprintf("%f", markdown.Options.PaperMargins[3])
+	values[landscape] = strconv.FormatBool(markdown.Options.Landscape)
+	return values
+}
+
+func (markdown *MarkdownRequest) getFormFiles() map[string]string {
+	if markdown.Options == nil {
+		markdown.Options = &MarkdownOptions{}
+	}
+	files := make(map[string]string)
+	files["index.html"] = markdown.IndexFilePath
+	files["header.html"] = markdown.Options.HeaderFilePath
+	files["footer.html"] = markdown.Options.FooterFilePath
+	for _, fpath := range markdown.MarkdownFilePaths {
+		files[filepath.Base(fpath)] = fpath
+	}
+	for _, fpath := range markdown.AssetFilePaths {
+		files[filepath.Base(fpath)] = fpath
+	}
+	return files
+}
+
+// Compile-time checks to ensure type implements desired interfaces.
+var (
+	_ = Request(new(MarkdownRequest))
+)
--- a/pkg/markdown_test.go
+++ b/pkg/markdown_test.go
@@ -0,0 +1,43 @@
+package gotenberg
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/thecodingmachine/gotenberg/internal/pkg/rand"
+	"github.com/thecodingmachine/gotenberg/test"
+)
+
+func TestMarkdown(t *testing.T) {
+	c := &Client{Hostname: "http://localhost:3000"}
+	req := &MarkdownRequest{
+		IndexFilePath: test.MarkdownTestFilePath(t, "index.html"),
+		MarkdownFilePaths: []string{
+			test.MarkdownTestFilePath(t, "paragraph1.md"),
+			test.MarkdownTestFilePath(t, "paragraph2.md"),
+			test.MarkdownTestFilePath(t, "paragraph3.md"),
+		},
+		AssetFilePaths: []string{
+			test.HTMLTestFilePath(t, "font.woff"),
+			test.HTMLTestFilePath(t, "img.gif"),
+			test.HTMLTestFilePath(t, "style.css"),
+		},
+		Options: &MarkdownOptions{
+			HeaderFilePath: test.MarkdownTestFilePath(t, "header.html"),
+			FooterFilePath: test.MarkdownTestFilePath(t, "footer.html"),
+			PaperSize:      A4,
+			PaperMargins:   NormalMargins,
+		},
+	}
+	dirPath, err := rand.Get()
+	require.Nil(t, err)
+	dest := fmt.Sprintf("%s/foo.pdf", dirPath)
+	err = c.Store(req, dest)
+	assert.Nil(t, err)
+	assert.FileExists(t, dest)
+	err = os.RemoveAll(dirPath)
+	assert.Nil(t, err)
+}
--- a/pkg/merge.go
+++ b/pkg/merge.go
@@ -0,0 +1,55 @@
+package gotenberg
+
+import (
+	"fmt"
+	"path/filepath"
+)
+
+// MergeRequest facilitates merging PDF
+// with the Gotenberg API.
+type MergeRequest struct {
+	FilePaths []string
+	Options   *MergeOptions
+}
+
+// MergeOptions gathers all options
+// for merging PDF
+// with the Gotenberg API.
+type MergeOptions struct {
+	WebHookURL string
+}
+
+func (merge *MergeRequest) validate() error {
+	for _, fpath := range merge.FilePaths {
+		if !fileExists(fpath) {
+			return fmt.Errorf("%s: PDF file does not exist", fpath)
+		}
+	}
+	return nil
+}
+
+func (merge *MergeRequest) getPostURL() string {
+	return "/merge"
+}
+
+func (merge *MergeRequest) getFormValues() map[string]string {
+	if merge.Options == nil {
+		merge.Options = &MergeOptions{}
+	}
+	values := make(map[string]string)
+	values[webhookURL] = merge.Options.WebHookURL
+	return values
+}
+
+func (merge *MergeRequest) getFormFiles() map[string]string {
+	files := make(map[string]string)
+	for _, fpath := range merge.FilePaths {
+		files[filepath.Base(fpath)] = fpath
+	}
+	return files
+}
+
+// Compile-time checks to ensure type implements desired interfaces.
+var (
+	_ = Request(new(MergeRequest))
+)
--- a/pkg/merge_test.go
+++ b/pkg/merge_test.go
@@ -0,0 +1,30 @@
+package gotenberg
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/thecodingmachine/gotenberg/internal/pkg/rand"
+	"github.com/thecodingmachine/gotenberg/test"
+)
+
+func TestMerge(t *testing.T) {
+	c := &Client{Hostname: "http://localhost:3000"}
+	req := &MergeRequest{
+		FilePaths: []string{
+			test.PDFTestFilePath(t, "gotenberg.pdf"),
+			test.PDFTestFilePath(t, "gotenberg.pdf"),
+		},
+	}
+	dirPath, err := rand.Get()
+	require.Nil(t, err)
+	dest := fmt.Sprintf("%s/foo.pdf", dirPath)
+	err = c.Store(req, dest)
+	assert.Nil(t, err)
+	assert.FileExists(t, dest)
+	err = os.RemoveAll(dirPath)
+	assert.Nil(t, err)
+}
--- a/pkg/office.go
+++ b/pkg/office.go
@@ -0,0 +1,55 @@
+package gotenberg
+
+import (
+	"fmt"
+	"path/filepath"
+)
+
+// OfficeRequest facilitates Office documents
+// conversion with the Gotenberg API.
+type OfficeRequest struct {
+	FilePaths []string
+	Options   *OfficeOptions
+}
+
+// OfficeOptions gathers all options
+// for Office documents conversion
+// with the Gotenberg API.
+type OfficeOptions struct {
+	WebHookURL string
+}
+
+func (office *OfficeRequest) validate() error {
+	for _, fpath := range office.FilePaths {
+		if !fileExists(fpath) {
+			return fmt.Errorf("%s: office file does not exist", fpath)
+		}
+	}
+	return nil
+}
+
+func (office *OfficeRequest) getPostURL() string {
+	return "/convert/office"
+}
+
+func (office *OfficeRequest) getFormValues() map[string]string {
+	if office.Options == nil {
+		office.Options = &OfficeOptions{}
+	}
+	values := make(map[string]string)
+	values[webhookURL] = office.Options.WebHookURL
+	return values
+}
+
+func (office *OfficeRequest) getFormFiles() map[string]string {
+	files := make(map[string]string)
+	for _, fpath := range office.FilePaths {
+		files[filepath.Base(fpath)] = fpath
+	}
+	return files
+}
+
+// Compile-time checks to ensure type implements desired interfaces.
+var (
+	_ = Request(new(OfficeRequest))
+)
--- a/pkg/office_test.go
+++ b/pkg/office_test.go
@@ -0,0 +1,29 @@
+package gotenberg
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/thecodingmachine/gotenberg/internal/pkg/rand"
+	"github.com/thecodingmachine/gotenberg/test"
+)
+
+func TestOffice(t *testing.T) {
+	c := &Client{Hostname: "http://localhost:3000"}
+	req := &OfficeRequest{
+		FilePaths: []string{
+			test.OfficeTestFilePath(t, "document.docx"),
+		},
+	}
+	dirPath, err := rand.Get()
+	require.Nil(t, err)
+	dest := fmt.Sprintf("%s/foo.pdf", dirPath)
+	err = c.Store(req, dest)
+	assert.Nil(t, err)
+	assert.FileExists(t, dest)
+	err = os.RemoveAll(dirPath)
+	assert.Nil(t, err)
+}