Freebox client in Golang

Usage

First get the library locally:

go get github.com/nikolalohinski/free-go

And use it as follows:

package main

import (
    "fmt"
    "context"

    "github.com/nikolalohinski/free-go/client"
)

func main() {
    var (
        endpoint     = "mafreebox.freebox.fr"
        version      = "latest" // Or pin a specific version such as v10.
        appID        = "..."    // See https://dev.freebox.fr/sdk/os/login/ and/or
        privateToken = "..."    // head to the next section of the documentation
    )

    ctx := context.Background()

    freebox, err := client.New(endpoint, version).
        WithAppID(appID).
        WithPrivateToken(privateToken)
    if err != nil {
        panic(err)
    }

    permissions, err := freebox.Login(ctx)
    if err != nil {
        panic(err)
    }

    fmt.Println(permissions)

    vms, err := freebox.ListVirtualMachines(ctx)
    if err != nil {
        panic(err)
    }

    fmt.Println(vms)
}

For details on how to use this client, please refer to the Client interface in client/client.go.

Generating credentials

At the time of this writing, generating credentials can only be done via the Freebox API. Please see the documentation of this terraform provider which leverages free-go to provide a simple CLI to interact with the API and generate tokens.

Supported and planned endpoints

• Authentication : /login/*
  • Request authorization
  • Track authorization progress (as part of the Request authorization process)
  • Getting the challenge value
  • Opening a session
  • Closing the current session
• Discovery over HTTP : /api_version
• Lan : /lan/*
  • Getting the list of browsable LAN interfaces
  • Getting the list of hosts on a given interface
  • Getting a host information
  • Updating a host information
  • Wake on LAN
  • Get the current Lan configuration
  • Update the current Lan configuration
• DHCP : /dhcp/*
  • Get the current DHCP configuration
  • Update the current DHCP configuration
  • List the DHCP static leases
  • Get a given DHCP static lease
  • Update DHCP static lease
  • Delete a DHCP static lease
  • Add a DHCP static lease
  • Get the list of DHCP dynamic leases
• Port forwarding: /fw/redir/*
  • Getting the list of port forwarding
  • Getting a specific port forwarding
  • Updating a port forwarding
  • Add a port forwarding
  • Delete a port forwarding
• Incoming port configuration : /fw/incoming/*
  • Getting the list of incoming ports
  • Getting a specific incoming port
  • Updating an incoming port
• Virtual machines (UNSTABLE) : /vm/*
  • Get VM System Info
  • Get Installable VM distributions
  • Get the list of all VMs
  • Get a VM
  • Add a VM
  • Delete a VM
  • Update a VM
  • Start a VM
  • Send a powerbutton signal to a VM
  • Stop a VM
  • Reset a VM
  • VM virtual console
  • VM virtual screen
  • Get information on a virtual disk
  • Create a virtual disk
  • Resize a virtual disk
  • Get a virtual disk task
  • Delete a virtual disk task
• Websocket API : /ws/*
  • WebSocket event API
  • WebSocket file Upload API
• Download API : /downloads/*
  • Get a download task
  • List download tasks
  • Delete a download task
  • Update a download task
  • Get a download log
  • Add a new download task
• Upload API : /upload/*
  • Get an upload task
  • List upload tasks
  • Delete an upload task
  • Cancel an upload task
  • Cleanup upload tasks
  • Start a new upload
• Filesystem API : /fs/*
  • Get file information
  • Download a file
  • Remove files
  • List files
  • Move files
  • Copy files
  • Concatenate files
  • Create an archive
  • Extract a file
  • Repair a file
  • Hash a file
  • Get a hash value
  • Create a directory
  • Rename a file/folder
  • List every task
  • Get a task
  • Delete a task
  • Update a task

Development

Requirements

• Install go (>= v1.20) following the official instructions ;
• Install mage using the online documentation ;
• Run the following to fetch all the required tools:

  mage install

• Verify the previous steps by running:

  mage

Tests

To run the unit tests:

mage go:test

To generate and open a coverage report:

mage go:cover

To run the integration tests, you will first need the following environment variables defined:

• FREEBOX_ENDPOINT: IP Address or DNS name to reach out to your Freebox. Usually mafreebox.freebox.fr works ;
• FREEBOX_VERSION: API version of the freebox you want to run against. For example v10 ;
• FREEBOX_APP_ID: The ID of the application you created to authenticate to the Freebox (see the login documentation) ;
• FREEBOX_TOKEN: The private token to authenticate to the Freebox (see the login documentation) ;

Then, you should be able to run:

mage go:integration

About

This project aims to provide the base Go components to create a terraform provider for the Freebox Delta to be able to leverage its VMs scheduling capabilities via infrastructure as code. It also aims to reach feature parity with juju2013/go-freebox, moul/go-freebox and eventually hacf-fr/freebox-api but with actual unit tests, maximal code coverage and integration testing.

Contributions are welcomed !