GitHunt
LI

Lightjohn/gowebdav

A golang WebDAV client library and command line tool.

GoWebDAV

Unit Tests Status
Build Artifacts Status
GoDoc
Go Report Card

A pure Golang WebDAV client library that comes with a reference implementation.

Features at a glance

Our gowebdav library allows to perform following actions on the remote WebDAV server:

It also provides an authentication API that makes it easy to encapsulate and control complex authentication challenges.
The default implementation negotiates the algorithm based on the user's preferences and the methods offered by the remote server.

Out-of-box authentication support for:

Usage

First of all you should create Client instance using NewClient() function:

root := "https://webdav.mydomain.me"
user := "user"
password := "password"

c := gowebdav.NewClient(root, user, password)
c.Connect()
// kick of your work!

After you can use this Client to perform actions, described below.

NOTICE: We will not check for errors in the examples, to focus you on the gowebdav library's code, but you should do it in your code!

Create path on a WebDAV server

err := c.Mkdir("folder", 0644)

In case you want to create several folders you can use c.MkdirAll():

err := c.MkdirAll("folder/subfolder/subfolder2", 0644)

Get files list

files, _ := c.ReadDir("folder/subfolder")
for _, file := range files {
    //notice that [file] has os.FileInfo type
    fmt.Println(file.Name())
}

Download file to byte array

webdavFilePath := "folder/subfolder/file.txt"
localFilePath := "/tmp/webdav/file.txt"

bytes, _ := c.Read(webdavFilePath)
os.WriteFile(localFilePath, bytes, 0644)

Download file via reader

Also you can use c.ReadStream() method:

webdavFilePath := "folder/subfolder/file.txt"
localFilePath := "/tmp/webdav/file.txt"

reader, _ := c.ReadStream(webdavFilePath)

file, _ := os.Create(localFilePath)
defer file.Close()

io.Copy(file, reader)

Upload file from byte array

webdavFilePath := "folder/subfolder/file.txt"
localFilePath := "/tmp/webdav/file.txt"

bytes, _ := os.ReadFile(localFilePath)

c.Write(webdavFilePath, bytes, 0644)

Upload file via writer

webdavFilePath := "folder/subfolder/file.txt"
localFilePath := "/tmp/webdav/file.txt"

file, _ := os.Open(localFilePath)
defer file.Close()

c.WriteStream(webdavFilePath, file, 0644)

For non-seekable stream, this will read data into memory first
to discover content length.

Upload file via writer with known length

webdavFilePath := "folder/subfolder/file.txt"

bytes := []byte{0x20, 0x20}

c.WriteStreamWithLength(webdavFilePath, bytes.NewBuffer(bytes), int64(len(data)), 0644)

Get information about specified file/folder

webdavFilePath := "folder/subfolder/file.txt"

info := c.Stat(webdavFilePath)
//notice that [info] has os.FileInfo type
fmt.Println(info)

Move file to another location

oldPath := "folder/subfolder/file.txt"
newPath := "folder/subfolder/moved.txt"
isOverwrite := true

c.Rename(oldPath, newPath, isOverwrite)

Copy file to another location

oldPath := "folder/subfolder/file.txt"
newPath := "folder/subfolder/file-copy.txt"
isOverwrite := true

c.Copy(oldPath, newPath, isOverwrite)

Delete file

webdavFilePath := "folder/subfolder/file.txt"

c.Remove(webdavFilePath)

More details about WebDAV server you can read from following resources:

NOTICE: RFC 2518 is obsoleted by RFC 4918 in June 2007

Contributing

All contributing are welcome. If you have any suggestions or find some bug - please create an Issue to let us make this project better. We appreciate your help!

License

This library is distributed under the BSD 3-Clause license found in the LICENSE file.

Stargazers over time

Stargazers over time

API

import "github.com/studio-b12/gowebdav"

Overview

Package gowebdav is a WebDAV client library with a command line tool
included.

Index

Examples
Package files

auth.go basicAuth.go client.go digestAuth.go doc.go errors.go file.go netrc.go passportAuth.go requests.go utils.go

Constants

const XInhibitRedirect = "X-Gowebdav-Inhibit-Redirect"

Variables

var ErrAuthChanged = errors.New("authentication failed, change algorithm")

ErrAuthChanged must be returned from the Verify method as an error
to trigger a re-authentication / negotiation with a new authenticator.

var ErrTooManyRedirects = errors.New("stopped after 10 redirects")

ErrTooManyRedirects will be used as return error if a request exceeds 10 redirects.

func FixSlash

func FixSlash(s string) string

FixSlash appends a trailing / to our string

func FixSlashes

func FixSlashes(s string) string

FixSlashes appends and prepends a / if they are missing

func IsErrCode

func IsErrCode(err error, code int) bool

IsErrCode returns true if the given error
is an os.PathError wrapping a StatusError
with the given status code.

func IsErrNotFound

func IsErrNotFound(err error) bool

IsErrNotFound is shorthand for IsErrCode
for status 404.

func Join

func Join(path0 string, path1 string) string

Join joins two paths

func NewPathError

func NewPathError(op string, path string, statusCode int) error

func NewPathErrorErr

func NewPathErrorErr(op string, path string, err error) error

func PathEscape

func PathEscape(path string) string

PathEscape escapes all segments of a given path

func ReadConfig

func ReadConfig(uri, netrc string) (string, string)

ReadConfig reads login and password configuration from ~/.netrc
machine foo.com login username password 123456

func String

func String(r io.Reader) string

String pulls a string out of our io.Reader

type AuthFactory

type AuthFactory func(c *http.Client, rs *http.Response, path string) (auth Authenticator, err error)

AuthFactory prototype function to create a new Authenticator

type Authenticator

type Authenticator interface {
    // Authorizes a request. Usually by adding some authorization headers.
    Authorize(c *http.Client, rq *http.Request, path string) error
    // Verifies the response if the authorization was successful.
    // May trigger some round trips to pass the authentication.
    // May also trigger a new Authenticator negotiation by returning `ErrAuthChenged`
    Verify(c *http.Client, rs *http.Response, path string) (redo bool, err error)
    // Creates a copy of the underlying Authenticator.
    Clone() Authenticator
    io.Closer
}

An Authenticator implements a specific way to authorize requests.
Each request is bound to a separate Authenticator instance.

The authentication flow itself is broken down into Authorize
and Verify steps. The former method runs before, and the latter
runs after the Request is submitted.
This makes it easy to encapsulate and control complex
authentication challenges.

Some authentication flows causing authentication round trips,
which can be archived by returning the redo of the Verify
method. True restarts the authentication process for the
current action: A new Request is spawned, which must be
authorized, sent, and re-verified again, until the action
is successfully submitted.
The preferred way is to handle the authentication ping-pong
within Verify, and then redo with fresh credentials.

The result of the Verify method can also trigger an
Authenticator change by returning the ErrAuthChanged
as an error. Depending on the Authorizer this may trigger
an Authenticator negotiation.

Set the XInhibitRedirect header to '1' in the Authorize
method to get control over request redirection.
Attention! You must handle the incoming request yourself.

To store a shared session state the Clone method must
return a new instance, initialized with the shared state.

func NewDigestAuth

func NewDigestAuth(login, secret string, rs *http.Response) (Authenticator, error)

NewDigestAuth creates a new instance of our Digest Authenticator

func NewPassportAuth

func NewPassportAuth(c *http.Client, user, pw, partnerURL string, header *http.Header) (Authenticator, error)

constructor for PassportAuth creates a new PassportAuth object and
automatically authenticates against the given partnerURL

type Authorizer

type Authorizer interface {
    // Creates a new Authenticator Shim per request.
    // It may track request related states and perform payload buffering
    // for authentication round trips.
    // The underlying Authenticator will perform the real authentication.
    NewAuthenticator(body io.Reader) (Authenticator, io.Reader)
    // Registers a new Authenticator factory to a key.
    AddAuthenticator(key string, fn AuthFactory)
}

Authorizer our Authenticator factory which creates an
Authenticator per action/request.

func NewAutoAuth

func NewAutoAuth(login string, secret string) Authorizer

NewAutoAuth creates an auto Authenticator factory.
It negotiates the default authentication method
based on the order of the registered Authenticators
and the remotely offered authentication methods.
First In, First Out.

func NewEmptyAuth

func NewEmptyAuth() Authorizer

NewEmptyAuth creates an empty Authenticator factory
The order of adding the Authenticator matters.
First In, First Out.
It offers the NewAutoAuth features.

func NewPreemptiveAuth

func NewPreemptiveAuth(auth Authenticator) Authorizer

NewPreemptiveAuth creates a preemptive Authenticator
The preemptive authorizer uses the provided Authenticator
for every request regardless of any Www-Authenticate header.

It may only have one authentication method,
so calling AddAuthenticator will panic!

Look out!! This offers the skinniest and slickest implementation
without any synchronisation!!
Still applicable with BasicAuth within go routines.

type BasicAuth

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

BasicAuth structure holds our credentials

func (*BasicAuth) Authorize

func (b *BasicAuth) Authorize(c *http.Client, rq *http.Request, path string) error

Authorize the current request

func (*BasicAuth) Clone

func (b *BasicAuth) Clone() Authenticator

Clone creates a Copy of itself

func (*BasicAuth) Close

func (b *BasicAuth) Close() error

Close cleans up all resources

func (*BasicAuth) String

func (b *BasicAuth) String() string

String toString

func (*BasicAuth) Verify

func (b *BasicAuth) Verify(c *http.Client, rs *http.Response, path string) (redo bool, err error)

Verify verifies if the authentication

type Client

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

Client defines our structure

func NewAuthClient

func NewAuthClient(uri string, auth Authorizer) *Client

NewAuthClient creates a new client instance with a custom Authorizer

func NewClient

func NewClient(uri, user, pw string) *Client

NewClient creates a new instance of client

func (*Client) Connect

func (c *Client) Connect() error

Connect connects to our dav server

func (*Client) Copy

func (c *Client) Copy(oldpath, newpath string, overwrite bool) error

Copy copies a file from A to B

func (*Client) Mkdir

func (c *Client) Mkdir(path string, _ os.FileMode) (err error)

Mkdir makes a directory

func (*Client) MkdirAll

func (c *Client) MkdirAll(path string, _ os.FileMode) (err error)

MkdirAll like mkdir -p, but for webdav

func (*Client) Read

func (c *Client) Read(path string) ([]byte, error)

Read reads the contents of a remote file

func (*Client) ReadDir

func (c *Client) ReadDir(path string) ([]os.FileInfo, error)

ReadDir reads the contents of a remote directory

func (*Client) ReadStream

func (c *Client) ReadStream(path string) (io.ReadCloser, error)

ReadStream reads the stream for a given path

func (*Client) ReadStreamRange

func (c *Client) ReadStreamRange(path string, offset, length int64) (io.ReadCloser, error)

ReadStreamRange reads the stream representing a subset of bytes for a given path,
utilizing HTTP Range Requests if the server supports it.
The range is expressed as offset from the start of the file and length, for example
offset=10, length=10 will return bytes 10 through 19.

If the server does not support partial content requests and returns full content instead,
this function will emulate the behavior by skipping offset bytes and limiting the result
to length.

func (*Client) Remove

func (c *Client) Remove(path string) error

Remove removes a remote file

func (*Client) RemoveAll

func (c *Client) RemoveAll(path string) error

RemoveAll removes remote files

func (*Client) Rename

func (c *Client) Rename(oldpath, newpath string, overwrite bool) error

Rename moves a file from A to B

func (*Client) SetHeader

func (c *Client) SetHeader(key, value string)

SetHeader lets us set arbitrary headers for a given client

func (*Client) SetInterceptor

func (c *Client) SetInterceptor(interceptor func(method string, rq *http.Request))

SetInterceptor lets us set an arbitrary interceptor for a given client

func (*Client) SetJar

func (c *Client) SetJar(jar http.CookieJar)

SetJar exposes the ability to set a cookie jar to the client.

func (*Client) SetTimeout

func (c *Client) SetTimeout(timeout time.Duration)

SetTimeout exposes the ability to set a time limit for requests

func (*Client) SetTransport

func (c *Client) SetTransport(transport http.RoundTripper)

SetTransport exposes the ability to define custom transports

func (*Client) Stat

func (c *Client) Stat(path string) (os.FileInfo, error)

Stat returns the file stats for a specified path

func (*Client) Write

func (c *Client) Write(path string, data []byte, _ os.FileMode) (err error)

Write writes data to a given path

func (*Client) WriteStream

func (c *Client) WriteStream(path string, stream io.Reader, _ os.FileMode) (err error)

WriteStream writes a stream - it will copy to memory for non-seekable streams

func (*Client) WriteStreamWithLength

func (c *Client) WriteStreamWithLength(path string, stream io.Reader, contentLength int64, _ os.FileMode) (err error)

WriteStream writes a stream with a known content length

type DigestAuth

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

DigestAuth structure holds our credentials

func (*DigestAuth) Authorize

func (d *DigestAuth) Authorize(c *http.Client, rq *http.Request, path string) error

Authorize the current request

func (*DigestAuth) Clone

func (d *DigestAuth) Clone() Authenticator

Clone creates a copy of itself

func (*DigestAuth) Close

func (d *DigestAuth) Close() error

Close cleans up all resources

func (*DigestAuth) String

func (d *DigestAuth) String() string

String toString

func (*DigestAuth) Verify

func (d *DigestAuth) Verify(c *http.Client, rs *http.Response, path string) (redo bool, err error)

Verify checks for authentication issues and may trigger a re-authentication

type File

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

File is our structure for a given file

func (File) ContentType

func (f File) ContentType() string

ContentType returns the content type of a file

func (File) ETag

func (f File) ETag() string

ETag returns the ETag of a file

func (File) IsDir

func (f File) IsDir() bool

IsDir let us see if a given file is a directory or not

func (File) ModTime

func (f File) ModTime() time.Time

ModTime returns the modified time of a file

func (File) Mode

func (f File) Mode() os.FileMode

Mode will return the mode of a given file

func (File) Name

func (f File) Name() string

Name returns the name of a file

func (File) Path

func (f File) Path() string

Path returns the full path of a file

func (File) Size

func (f File) Size() int64

Size returns the size of a file

func (File) String

func (f File) String() string

String lets us see file information

func (File) Sys

func (f File) Sys() interface{}

Sys ????

type PassportAuth

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

PassportAuth structure holds our credentials

func (*PassportAuth) Authorize

func (p *PassportAuth) Authorize(c *http.Client, rq *http.Request, path string) error

Authorize the current request

func (*PassportAuth) Clone

func (p *PassportAuth) Clone() Authenticator

Clone creates a Copy of itself

func (*PassportAuth) Close

func (p *PassportAuth) Close() error

Close cleans up all resources

func (*PassportAuth) String

func (p *PassportAuth) String() string

String toString

func (*PassportAuth) Verify

func (p *PassportAuth) Verify(c *http.Client, rs *http.Response, path string) (redo bool, err error)

Verify verifies if the authentication is good

type StatusError

type StatusError struct {
    Status int
}

StatusError implements error and wraps
an erroneous status code.

func (StatusError) Error

func (se StatusError) Error() string

Generated by godoc2md

Languages

Go98.7%Makefile1.3%
BSD 3-Clause "New" or "Revised" License
Created January 19, 2026
Updated January 19, 2026