ExGitEngine.WireProtocol behaviour (ex_git_engine v0.9.3)

Copy Markdown

Conveniences for Git transport protocol and server side commands.

This module implements version 2 of Git's wire protocol.

It functions as a very basic finite-state machine by processing incoming client requests and forwarding them to the underlying service implementation (respectively receive-pack and upload-pack).

The state machine is initialized by calling new/2 with the Git repository and command to execute. By passing incoming data to next/2, the underlying service transit to the next state. Once the client and the server are done with exchanging Git objects, the service will reach the :done state.

When processing a entire (not chunked), one can use run/2 to execute all the steps in a single call.

Summary

Callbacks

next(struct, list)

Callback used to transist a service to the next step.

skip(struct)

Callback used to transist a service to the next step without performing any action.

Functions

decode(pkt)

Returns a stream of decoded PKT-LINEs for the given pkt.

done?(service)

Returns true if service is done; elsewise returns false.

encode(lines, caps \\ [])

Returns an PKT-LINE encoded representation of the given lines.

new(agent, executable, init_values \\ [])

Returns a new service object for the given repo and executable.

next(service, data \\ :discovery)

Runs the given service to the next step.

pkt_line(data \\ :flush)

Returns the given data formatted as PKT-LINE

pkt_line(pack, caps)
reference_discovery(agent, service, no_done \\ false)

Returns a stream describing each ref and it current value.

run(service, data \\ :discovery, opts \\ [])

Runs all the steps of the given service at once.

server_agent_capability()

Returns the agent capability string for ex_git_engine.

server_capabilities(binary)

Returns the list of server capabilities for the given service.

skip(service)

Sets the given service to the next logical step without performing any action.

valid_services()

Returns the list of git services implemented by this library.

validate_capabilities(client_caps, advertised_caps)

Validates client capabilities against advertised capabilities.

Callbacks

next(struct, list)

@callback next(
  struct(),
  [term()]
) :: {struct(), [term()], iolist()}

Callback used to transist a service to the next step.

skip(struct)

@callback skip(struct()) :: struct()

Callback used to transist a service to the next step without performing any action.

Functions

decode(pkt)

@spec decode(binary()) :: Enumerable.t()

Returns a stream of decoded PKT-LINEs for the given pkt.

done?(service)

@spec done?(struct()) :: boolean()

Returns true if service is done; elsewise returns false.

encode(lines, caps \\ [])

@spec encode(Enumerable.t(), list()) :: iolist()

Returns an PKT-LINE encoded representation of the given lines.

new(agent, executable, init_values \\ [])

@spec new(ExGitEngine.GitAgent.agent(), binary(), keyword()) ::
  struct() | {:error, :unknown_service}

Returns a new service object for the given repo and executable.

next(service, data \\ :discovery)

@spec next(
  struct(),
  :discovery
) :: {struct(), iolist()}
@spec next(
  struct(),
  binary()
) :: {:cont | :halt, struct(), iolist()}

Runs the given service to the next step.

pkt_line(data \\ :flush)

@spec pkt_line(
  :flush
  | {:ack, ExGitEngine.Git.oid()}
  | {:ack, ExGitEngine.Git.oid(), binary()}
  | :nak
  | binary()
  | {:sideband_report, integer(), [term()]}
  | {:sideband, integer(), binary()}
  | {:sideband_pack, integer(), binary()}
  | {:unpack, binary()}
  | {:ok, binary()}
  | {:ng, binary(), binary()}
) :: binary()

Returns the given data formatted as PKT-LINE

pkt_line(pack, caps)

reference_discovery(agent, service, no_done \\ false)

@spec reference_discovery(ExGitEngine.GitAgent.agent(), binary(), boolean()) :: [
  term()
]

Returns a stream describing each ref and it current value.

run(service, data \\ :discovery, opts \\ [])

@spec run(struct(), binary() | :discovery, keyword()) :: {struct(), iolist()}

Runs all the steps of the given service at once.

server_agent_capability()

Returns the agent capability string for ex_git_engine.

server_capabilities(binary)

Returns the list of server capabilities for the given service.

skip(service)

@spec skip(struct()) :: struct()

Sets the given service to the next logical step without performing any action.

valid_services()

@spec valid_services() :: [binary()]

Returns the list of git services implemented by this library.

validate_capabilities(client_caps, advertised_caps)

Validates client capabilities against advertised capabilities.

Returns a list of unknown capabilities requested by the client.