webntp

README

WebNTP

WebNTP is NTP(-like) service via HTTP/WebSocket.

Synopsis

First, go install and start the WebNTP Server.

$ go install github.com/shogo82148/go-webntp/cmd/webntp
$ webntp -serve :8080

Sync with the server via HTTP.

$ webntp http://localhost:8080/
server http://localhost:8080/, offset -0.000066, delay 0.001453
2017-03-11 18:25:10.905049427 +0900 JST, server http://localhost:8080/, offset -0.000066

Sync with the server via WebSocket.

$ webntp ws://localhost:8080/
server ws://localhost:8080/, offset -0.000013, delay 0.000288
2017-03-11 18:25:36.668531757 +0900 JST, server ws://localhost:8080/, offset -0.000013

I provide a public WebNTP API.

$ webntp https://webntp.shogo82148.com/api
server https://webntp.shogo82148.com/api, offset -0.006376, delay 0.024411
2017-03-11 16:08:06.150393313 +0900 JST, server https://webntp.shogo82148.com/api, offset -0.006376

Shared Memory support for ntpd

Add a new server to your ntpd.conf.

server 127.127.28.2 noselect
fudge 127.127.28.2 refid PYTH stratum 10

Run WebNTP with -shm 2 option.

$ webntp -p 1 -shm 2 https://webntp.shogo82148.com/api
server https://webntp.shogo82148.com/api, offset -0.003258, delay 0.018910

ntpd starts syncing with WebNTP.

$ ntpq -p
     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
 SHM(2)          .PYTH.          10 l    2   64   17    0.000   -3.331   0.384
*webntp.shogo82. .NICT.           1 u   58   64   37   10.280    1.494   2.028

Usage

$ webntp --help
  -allow-cross-origin
    	allow cross origin request
  -help
    	show help
  -leap-second-path string
    	path for leap-seconds.list cache (default "leap-seconds.list")
  -leap-second-url string
    	url for leap-seconds.list (default "https://www.ietf.org/timezones/data/leap-seconds.list")
  -p int
    	Specify the number of samples (default 4)
  -serve string
    	server host name
  -shm uint
    	ntpd shared-memory-segment

Protocol

JSON over HTTP

The WebNTP clients access to http://example.com/?<timestamp>, and then the WebNTP server returns the time information formatted by JSON.

• id: hostname of the server
• it: the client's timestamp of the request transmission
• st: the server's timestamp
• leap: the seconds of TAI - UTC (before next)
• next: the timestamp of the next or last leap second
• step: positive leap second: 1, negative leap second: -1

Example:

$ curl -s http://localhost:8080/?1489217288.328757 | jq .
{
  "id": "localhost:8080",
  "it": 1489217288.328757,
  "st": 1489224472.995564,
  "time": 1489224472.995564,
  "leap": 36,
  "next": 1483228800,
  "step": 1
}

It is based on the document of http/https service by NICT (the National Institute of Information and Communications Technology). (the content is written in Japanese)

JSON over WebSocket

The WebNTP clients send a message including timestamp, and then the WebNTP server returns the time information formatted by JSON. JSON format is same as HTTP response.

Example:

$ wscat --connect localhost:8080
connected (press CTRL+C to quit)
> 1558915619.944235
< {"id":"localhost:8080","it":1558915619.944235,"st":1558916776.363423,"time":1558916776.363423,"leap":36,"next":1483228800.000000,"step":1}

Time over HTTPS with Improved timekeeping response

The clients send HEAD /.well-known/time HTTP request, and then the server returns the timestamp in the response header.

X-HTTPSTIME: <timestamp>

Example:

$ curl -I localhost:8080
HTTP/1.1 204 No Content
X-Httpstime: 1558915632.285965
Date: Mon, 27 May 2019 00:07:12 GMT

It is based on Time over HTTPS specification.

License

This software is released under the MIT License, see LICENSE.

SEE ALSO

• Time over HTTPS
• htp
• http/httpsを利用した時刻配信(アーカイブ) (The time server using http/https (archived))

Documentation

Index

• Constants
• Variables
• type Client
  • func (c *Client) Get(ctx context.Context, uri string) (Result, error)
  • func (c *Client) GetMulti(ctx context.Context, uri string, samples int) (Result, error)
• type LeapSecond
• type LeapSecondsList
  • func ParseLeapSecondsList(r io.Reader) (*LeapSecondsList, error)
• type Response
• type Result
• type Server
  • func (s *Server) Close() error
  • func (s *Server) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (s *Server) Start() error
• type Timestamp
  • func (t Timestamp) MarshalJSON() ([]byte, error)
  • func (t *Timestamp) UnmarshalJSON(b []byte) error

Constants

const Subprotocol = "webntp.shogo82148.com"

Subprotocol is a subprotocol name for websocket.

Variables

var DefaultDialer = &websocket.Dialer{
	Proxy:        http.ProxyFromEnvironment,
	Subprotocols: []string{Subprotocol},
}

DefaultDialer is a dialer for webntp.

Types

type Client

type Client struct {
	HTTPClient *http.Client
	Dialer     *websocket.Dialer
}

Client is a webntp client.

func (*Client) Get

func (c *Client) Get(ctx context.Context, uri string) (Result, error)

Get gets synchronization information.

func (*Client) GetMulti

func (c *Client) GetMulti(ctx context.Context, uri string, samples int) (Result, error)

GetMulti gets synchronization information. It improve accuracy by calling the Get method many times.

type LeapSecond

type LeapSecond struct {
	// At is the time to insert/delete a leap second.
	At time.Time

	// Leap is offset from TAI to UTC. (**after** LeapSecond.Time)
	Leap int

	// Step describes next leap second is insertion or deletion.
	// +1 is insertion, -1 is deletion.
	Step int
}

LeapSecond is information for leap-seconds

type LeapSecondsList

type LeapSecondsList struct {
	LeapSeconds []LeapSecond
	UpdateAt    time.Time
	ExpireAt    time.Time
}

LeapSecondsList is the contents of leap-second.list.

func ParseLeapSecondsList

func ParseLeapSecondsList(r io.Reader) (*LeapSecondsList, error)

ParseLeapSecondsList parses leap-second.list.

type Response

type Response struct {
	// ID is the id of the web-ntp server.
	ID string `json:"id"`

	// InitiateTime is the time that the request has been sent.
	InitiateTime Timestamp `json:"it"`

	// SendTime is the time that the response has been sent.
	SendTime Timestamp `json:"st"`

	// Time is a same as SendTime.
	// It is for htptime compatibility.
	Time Timestamp `json:"time"`

	// Leap is from TAI to UTC. (**before** Response.Next)
	Leap int `json:"leap"`

	// Next is the time of next or last leap second event.
	Next Timestamp `json:"next"`

	// Step describes next or last leap second is insertion or deletion.
	// +1 is insertion, -1 is deletion.
	Step int `json:"step"`
}

Response is a response from webntp server.

type Result

type Result struct {
	Offset    time.Duration
	Delay     time.Duration
	NextLeap  time.Time
	TAIOffset time.Duration
	Step      int
}

Result is the result of synchronization.

type Server

type Server struct {
	Upgrader *websocket.Upgrader

	// path for leap-seconds.list cache
	LeapSecondsPath string

	// url for leap-seconds.list
	LeapSecondsURL string
	// contains filtered or unexported fields
}

Server is a webntp server.

func (*Server) Close

func (s *Server) Close() error

Close closes the server.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(rw http.ResponseWriter, req *http.Request)

func (*Server) Start

func (s *Server) Start() error

Start starts fetching leap-seconds.list

type Timestamp

type Timestamp time.Time

Timestamp is posix unix timestamp.

func (Timestamp) MarshalJSON

func (t Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON converts the timestamp to JSON number. The number is unix timestamp.

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(b []byte) error

UnmarshalJSON converts JSON number to a timestamp. The number is unix timestamp.