lfsx_server/
config.rs

1use axum::http::{HeaderMap, header};
2
3use std::net::SocketAddr;
4use std::path::PathBuf;
5use std::time::Duration;
6
7use crate::model::Action;
8use crate::namespace::Namespace;
9
10#[derive(Debug, Clone)]
11pub struct Config {
12    pub bind: SocketAddr,
13    pub storage_root: PathBuf,
14    pub public_url: Option<String>,
15    pub action_lifetime: u32,
16    pub gc_grace: Duration,
17    pub staging_max_age: Duration,
18    // How long a lock may go untouched before anyone can take it. Unset means
19    // never, which is what happened before this existed and what a team that has
20    // not thought about it yet should keep getting.
21    pub lock_max_age: Option<Duration>,
22    pub max_object_size: Option<u64>,
23    pub repo_quota: Option<u64>,
24    pub compression: Option<i32>,
25    // A path rather than the key itself: a key in the environment is in the pod
26    // spec, in `docker inspect`, and in every log that dumps the environment. A
27    // file comes from a Kubernetes Secret mount or FerrVault without any of that.
28    pub encryption_key_file: Option<PathBuf>,
29    pub storage: Storage,
30    pub auth: Auth,
31}
32
33#[derive(Debug, Clone)]
34pub enum Storage {
35    Local,
36    // Endpoint, bucket and credentials all have to be there: a bucket the server
37    // cannot reach is a server that answers every push with an error, and
38    // discovering that on the first upload rather than at boot is the wrong
39    // order.
40    Bucket {
41        endpoint: String,
42        bucket: String,
43        region: String,
44        access_key: String,
45        secret_key: String,
46        path_style: bool,
47        // Whether a download is redirected to the bucket instead of streamed
48        // through this server. Off by default: the streamed path is the one
49        // that counts bytes, serves ranges and holds the ceiling, and an
50        // operator should choose to give those up rather than discover it.
51        presign: bool,
52        // Whether locks can be taken here. Not read from the environment: it
53        // starts true and the startup probes turn it off, the same way they turn
54        // `presign` off, when the store will not prove it can arbitrate between
55        // two writers racing for the same key.
56        locking: bool,
57    },
58}
59
60impl Storage {
61    fn from_env() -> Self {
62        if std::env::var("LFSX_STORAGE").as_deref() != Ok("s3") {
63            return Self::Local;
64        }
65
66        let required = |name: &str| {
67            std::env::var(name)
68                .ok()
69                .filter(|value| !value.is_empty())
70                .unwrap_or_else(|| panic!("LFSX_STORAGE=s3 needs {name}"))
71        };
72
73        Self::Bucket {
74            endpoint: required("LFSX_S3_ENDPOINT"),
75            bucket: required("LFSX_S3_BUCKET"),
76            region: std::env::var("LFSX_S3_REGION").unwrap_or_else(|_| "us-east-1".into()),
77            access_key: required("LFSX_S3_ACCESS_KEY"),
78            secret_key: required("LFSX_S3_SECRET_KEY"),
79            path_style: std::env::var("LFSX_S3_PATH_STYLE").as_deref() != Ok("false"),
80            presign: std::env::var("LFSX_S3_PRESIGN").as_deref() == Ok("true"),
81            locking: true,
82        }
83    }
84}
85
86#[derive(Debug, Clone)]
87pub enum Auth {
88    Forge {
89        provider: Provider,
90        api_url: String,
91        cache_ttl: Duration,
92        rejection_ttl: Duration,
93        // Whether a request with no credentials is resolved against the forge
94        // instead of refused. On by default, because that is what cloning a
95        // public repository does everywhere else.
96        anonymous_read: bool,
97    },
98    Disabled,
99}
100
101#[derive(Debug, Clone, Copy, PartialEq, Eq)]
102pub enum Provider {
103    Github,
104    Gitlab,
105    // Gitea and Forgejo, which are one API: Forgejo is a fork of Gitea and
106    // answers the same routes, so the only thing that tells two instances apart
107    // is the root they are reached at.
108    Gitea,
109}
110
111impl Provider {
112    // None where there is no such thing as the instance.
113    //
114    // github.com and gitlab.com are where a repository is unless the operator
115    // says otherwise, so defaulting there is nearly always right. Gitea is
116    // software rather than a place. gitea.com exists, but an operator who names
117    // this provider is almost certainly running their own, and quietly resolving
118    // their namespaces against a stranger's forge is worse than not starting: a
119    // public repository there that happens to share a name would hand out
120    // anonymous read on objects it has nothing to do with.
121    fn default_api_url(self) -> Option<&'static str> {
122        match self {
123            Self::Github => Some("https://api.github.com"),
124            Self::Gitlab => Some("https://gitlab.com/api/v4"),
125            Self::Gitea => None,
126        }
127    }
128
129    fn api_url_variable(self) -> &'static str {
130        match self {
131            Self::Github => "LFSX_GITHUB_API_URL",
132            Self::Gitlab => "LFSX_GITLAB_API_URL",
133            Self::Gitea => "LFSX_GITEA_API_URL",
134        }
135    }
136}
137
138const CACHE_TTL: Duration = Duration::from_secs(60);
139const REJECTION_TTL: Duration = Duration::from_secs(10);
140const GC_GRACE: Duration = Duration::from_secs(14 * 24 * 60 * 60);
141const STAGING_MAX_AGE: Duration = Duration::from_secs(24 * 60 * 60);
142
143impl Config {
144    pub fn from_env() -> Self {
145        let bind = std::env::var("LFSX_BIND")
146            .ok()
147            .and_then(|raw| raw.parse().ok())
148            .unwrap_or_else(|| SocketAddr::from(([0, 0, 0, 0], 8080)));
149
150        let storage_root = std::env::var("LFSX_STORAGE_ROOT")
151            .map(PathBuf::from)
152            .unwrap_or_else(|_| PathBuf::from("/var/lib/lfsx"));
153
154        let public_url = std::env::var("LFSX_PUBLIC_URL")
155            .ok()
156            .filter(|url| !url.is_empty())
157            .map(|url| url.trim_end_matches('/').to_owned());
158
159        Self {
160            bind,
161            storage_root,
162            public_url,
163            action_lifetime: 1800,
164            gc_grace: seconds("LFSX_GC_GRACE").unwrap_or(GC_GRACE),
165            staging_max_age: seconds("LFSX_STAGING_MAX_AGE").unwrap_or(STAGING_MAX_AGE),
166            lock_max_age: seconds("LFSX_LOCK_MAX_AGE"),
167            max_object_size: bytes("LFSX_MAX_OBJECT_SIZE"),
168            repo_quota: bytes("LFSX_REPO_QUOTA"),
169            compression: compression(),
170            encryption_key_file: std::env::var("LFSX_ENCRYPTION_KEY_FILE")
171                .ok()
172                .filter(|path| !path.is_empty())
173                .map(PathBuf::from),
174            storage: Storage::from_env(),
175            auth: Auth::from_env(),
176        }
177    }
178
179    pub fn base_url(&self, headers: &HeaderMap) -> String {
180        if let Some(configured) = &self.public_url {
181            return configured.clone();
182        }
183
184        let scheme = headers
185            .get("x-forwarded-proto")
186            .and_then(|value| value.to_str().ok())
187            .and_then(|value| value.split(',').next())
188            .map(str::trim)
189            .filter(|scheme| !scheme.is_empty())
190            .unwrap_or("http");
191
192        let authority = headers
193            .get(header::HOST)
194            .and_then(|value| value.to_str().ok())
195            .map(str::trim)
196            .filter(|host| !host.is_empty())
197            .unwrap_or("localhost");
198
199        format!("{scheme}://{authority}")
200    }
201
202    pub fn object_url(&self, base: &str, ns: &Namespace, oid: &str) -> String {
203        format!("{base}/{ns}/objects/{oid}")
204    }
205
206    pub fn verify_url(&self, base: &str, ns: &Namespace) -> String {
207        format!("{base}/{ns}/objects/verify")
208    }
209
210    pub fn action(&self, href: String) -> Action {
211        Action {
212            href,
213            header: None,
214            expires_in: self.action_lifetime,
215        }
216    }
217
218    pub fn signed_action(&self, href: String, headers: Vec<(String, String)>) -> Action {
219        Action {
220            href,
221            header: Some(headers.into_iter().collect()),
222            expires_in: self.action_lifetime,
223        }
224    }
225}
226
227// Opt in, not opt out. Serving objects to a caller with no credentials at all is
228// a decision an operator should make on purpose: it costs them the bandwidth of
229// anyone who finds the endpoint, on a server whose whole job is to move files
230// measured in gigabytes. Nothing confidential is at stake, since a request with
231// no credentials is still resolved against the forge and a private repository is
232// still refused, but "anyone may pull from you" is not a sensible thing to
233// inherit by default.
234//
235// Only the exact string opens it. A typo, an empty value or a `1` leaves it
236// closed, because the failure that matters here is the one that opens the door
237// when nobody meant to.
238fn anonymous_read(value: Option<&str>) -> bool {
239    value == Some("true")
240}
241
242impl Auth {
243    fn from_env() -> Self {
244        if std::env::var("LFSX_AUTH").as_deref() == Ok("disabled") {
245            tracing::warn!(
246                "LFSX_AUTH=disabled — every request is accepted, run this on a trusted network only"
247            );
248            return Self::Disabled;
249        }
250
251        let provider = provider(std::env::var("LFSX_AUTH").ok().as_deref());
252
253        Self::Forge {
254            provider,
255            api_url: api_url(
256                provider,
257                std::env::var(provider.api_url_variable()).ok().as_deref(),
258            ),
259            cache_ttl: seconds("LFSX_AUTH_CACHE_TTL").unwrap_or(CACHE_TTL),
260            rejection_ttl: seconds("LFSX_AUTH_REJECTION_TTL").unwrap_or(REJECTION_TTL),
261            anonymous_read: anonymous_read(std::env::var("LFSX_ANONYMOUS_READ").ok().as_deref()),
262        }
263    }
264}
265
266// Anything unrecognised is GitHub, which is what an operator who set nothing
267// almost certainly meant. Forgejo is named alongside Gitea because they are one
268// API, and somebody running Forgejo should not have to know it began as a fork.
269fn provider(value: Option<&str>) -> Provider {
270    match value {
271        Some("gitlab") => Provider::Gitlab,
272        Some("gitea") | Some("forgejo") => Provider::Gitea,
273        _ => Provider::Github,
274    }
275}
276
277// The trailing slash matters: every route is built by appending to this, so one
278// left on the end produces `//repos/...`, which some forges answer and others do
279// not, and the ones that do not answer 404 for a repository that is right there.
280fn api_url(provider: Provider, configured: Option<&str>) -> String {
281    let variable = provider.api_url_variable();
282
283    configured
284        .map(str::to_owned)
285        .or_else(|| provider.default_api_url().map(str::to_owned))
286        .unwrap_or_else(|| {
287            panic!(
288                "{variable} must be set: a self-hosted forge has no default API root, and guessing \
289                 one would resolve your repositories against somebody else's"
290            )
291        })
292        .trim_end_matches('/')
293        .to_owned()
294}
295
296// Unset means unlimited, which is what a server on its own volume wants. Zero
297// would refuse every push, so it is read as a typo rather than as a policy
298// nobody would choose deliberately.
299// zstd level 3 is the default because it is the one that costs nothing you can
300// measure: it compresses faster than a spinning disk writes, and the meshes and
301// uncompressed raster that make up most of an LFS store give most of their
302// ground at any level. Higher levels are there for a store that is short on
303// room rather than on time.
304fn compression() -> Option<i32> {
305    match std::env::var("LFSX_COMPRESSION").ok()?.trim() {
306        "" | "none" | "off" => None,
307        "zstd" => Some(3),
308        other => match other
309            .strip_prefix("zstd:")
310            .and_then(|level| level.parse().ok())
311        {
312            Some(level @ 1..=19) => Some(level),
313            _ => {
314                tracing::warn!(
315                    "LFSX_COMPRESSION={other} is not a codec this server knows — storing objects as they arrive"
316                );
317                None
318            }
319        },
320    }
321}
322
323fn bytes(variable: &str) -> Option<u64> {
324    let configured = std::env::var(variable).ok()?.trim().parse().ok()?;
325
326    if configured == 0 {
327        tracing::warn!("{variable}=0 would refuse every upload — ignoring it");
328        return None;
329    }
330
331    Some(configured)
332}
333
334fn seconds(variable: &str) -> Option<Duration> {
335    std::env::var(variable)
336        .ok()
337        .and_then(|raw| raw.parse().ok())
338        .map(Duration::from_secs)
339}
340
341#[cfg(test)]
342mod tests;
lfsx_server/config.rs

lfsx_server/
config.rs
